코딩 에이전트 (Coding agent)가 무언가 잘못하면, 당신은 그것을 빠르게 알아차립니다. 빌드가 실패하거나, 테스트가 실패(red)하거나, 페이지가 빈 화면으로 렌더링되거나, 혹은 당신이 놓칠 수 없을 만큼 요란하게 무언가가 무너집니다. 하지만 연구 에이전트 (Research agent)가 무언가 잘못하면, 당신은 잘못된 사실들로 가득 찬, 아름답게 서식화된 브리프 (Brief)를 받게 됩니다.

그리고 문서화 작업은 연구를 기반으로 진행됩니다.

제가 지난 2월에 이 작업에 대해 남겼던 한 문장

지난 2월에 저는 문서화 티켓 (Documentation ticket)의 연구 단계를 수행하기 위해 구축한 명령 (Command)에 대해 글을 쓴 적이 있습니다. 티켓 ID를 입력하면, 해당 티켓과 모든 댓글을 가져오고, 연결된 엔지니어링 이슈 (Engineering issues)를 추적하며, 내부 위키 (Internal wiki)에서 PRD 또는 사양서 (Spec)를 찾아 헤매고, 이미 게시된 페이지들을 읽은 뒤, 하단에 미결 질문 (Open questions)이 포함된 구조화된 브리프 (Brief)를 반환합니다.

저는 결과에 만족했습니다. 도구들 사이를 클릭하며 시간을 허비하는 것을 몇 시간이나 줄여주었고, 우리 내부 위키의 검색 엔진이 형편없었기 때문에 제가 놓쳤을 법한 사항들을 찾아내 주었습니다.

그 포스트를 다시 읽어보니, 무엇이 잘못될 수 있는지에 대한 섹션 전체가 단 한 문장으로 되어 있었습니다: 여전히 정보를 검토하고 이해관계자 (Stakeholders)와 확인하여 초안이 정확한지 확인해야 한다는 내용입니다. 그것은 맞는 말이지만, 결코 충분하지 않습니다. 만약 당신이 이런 도구를 만들고 있다면, 그 문장이 바로 당신의 리스크 (Risk)가 가장 많이 잠재된 지점입니다.

브리프 (Brief)는 당신의 파이프라인에서 가장 위험한 요소입니다

그 이후의 모든 과정은 브리프 (Brief)를 기반으로 구축됩니다. 당신은 브리프를 읽고, 그것을 바탕으로 초안을 작성하며, 그 초안은 엔지니어에게 전달되어 엔지니어는 그것을 해당 기능에 대한 당신의 이해로 받아들입니다. 그들은 당신의 문장을 검토하는 것이지, 그것을 생성해낸 검색 (Retrieval) 과정을 검토하는 것이 아닙니다.

따라서 브리프 (Brief)의 오류는 발견되기를 기다리며 가만히 머물러 있지 않습니다. 그것은 페이지에 기록되고, 당신이 읽기를 수행했을 것이라고 합리적으로 가정하는 누군가에 의해 승인됩니다. 그 체인의 어딘가에서 그것은 도구의 실수가 아니라 당신의 판단 (Judgement)이 됩니다.

주의 깊게 읽는 것만으로는 당신을 구원할 수 없습니다

산문(Prose)에는 실패 상태라는 것이 없습니다. 존재하지 않는 PRD(제품 요구 사항 문서)에 대한 인용은 존재하는 것에 대한 인용과 정확히 동일한 형식으로 작성됩니다. 잘못된 팀에 할당된 이해관계자(Stakeholder)도 아주 완벽하게 읽힙니다. 아무것도 빨간색으로 표시되지 않습니다.

그리고 당신은 아직 자료를 모르기 때문에 브리프(Brief)를 읽고 있는 것인데, 그것이 바로 당신이 브리프를 요청한 근본적인 이유였습니다. 즉, 당신은 아직 시스템에 대한 구상을 형성하고 있는 단계에서, 무언가 누락된 것을 알아차릴 준비가 가장 되어 있지 않은 바로 그 순간에, 근거가 되는 소스들을 읽기도 전에 요약본을 확인하고 있는 것입니다.

저는 잘 모르겠지만, 저는 지저분한 문서보다 깔끔하게 정리된 문서를 더 신뢰하는 경향이 있습니다. 구조(Structure)는 이러한 도구들이 진정으로 잘하는 분야입니다. 정확도(Accuracy)는 이들이 가장 못하는 분야입니다. 이는 당신이 평소에 엉성한 작업을 잡아내기 위해 사용하는 본능이 잘못된 신호를 향하게 된다는 것을 의미합니다.

독자 앞에 회의론자를 배치하세요

만약 당신이 이미 에이전트(Agent)의 작업 끝에 회의적인 검토 단계를 두고 있다면—즉, 오직 공격하는 것만이 유일한 임무인 두 번째 에이전트에게 결과물을 넘기는 방식이라면—당신은 아마도 그 단계를 마지막에 실행하고 있을 것입니다. 연구(Research)에 있어서 그것은 너무 늦습니다. 연구 에이전트가 브리프가 생성되는 즉시 새로운 적대적(Adversarial) 에이전트를 생성하도록 설정하고, 어떤 내용이 당신에게 도달하기 전에 브리프의 사실 관계를 확인(Fact-check)하도록 만드세요.

검토 범위를 좁게 유지하세요. "이것이 괜찮은가?"가 아니라 다음과 같이 질문해야 합니다: 각 주장이 실제로 검색된 내용으로 추적 가능한가? 여기에 있는 내용 중 서로 모순되는 것이 있는가? 정보가 최신인가, 아니면 몇 년 전 버려진 오래된 페이지에 기반하고 있는가? 그리고 누락된 부분(Gaps)이 누락된 것으로 표시되어 있는가?

마지막 질문이 가장 큰 비중을 차지합니다. 에이전트에게 연구 브리프를 요청하면 당신은 연구 브리프를 받게 될 것입니다. 에이전트는 브리프의 4분의 3만 건네주며 나머지는 없다고 말하지 않을 것입니다. 우리가 경계해야 할 실패는, 정직한 출력값이 "위키에 이에 대한 내용이 없으니 사람에게 물어보세요"였어야 할 상황에서, 매끄럽고 완벽해 보이는 답변이 나오는 상황입니다.

그에 따른 비용

속도가 더 느려지는데, 이는 더 빠르게 가기 위해 구축된 워크플로우(Workflow) 관점에서는 불합리해 보일 수도 있습니다. 하지만 그것은 당신이 직접 40개의 위키 페이지를 찾는 것보다는 훨씬 빠르며, 기다림에 대한 보상을 얻게 됩니다.

그것이 요약본을 진실하게 만들어주지는 않을 것입니다. 새로운 시각을 가진 사람이 포착하는 것은, 근거가 없는 사실들, 빈약한 증거에 기반한 주장들, 그리고 매끄럽게 다듬어져 버린 공백들입니다. 제가 계속해서 마주쳤던 것들이 바로 그런 것들이었습니다.

당신이 작성한 글은 여전히 당신보다 시스템을 더 잘 아는 사람에게 전달되며, 그 검토 (review) 과정은 선택 사항이 아닙니다. 회의적인 관점 (skeptical pass)을 거친다는 것은, 단지 아무 이유 없이 덜 믿게 된 상태로 그 대화에 참여하게 된다는 것을 의미할 뿐입니다.