코딩 에이전트를 더 적은 감독으로 일하게 하려면 지시를 계속 덧붙이기보다 프로젝트의 배경과 판단 근거를 저장소에 남겨야 한다. 에이전트와 함께 일해 온 경험을 바탕으로, 에이전트에 맞춰 문서를 쓰는 법과 새 저장소에 추가할 기본 문서를 소개한다.

에이전트를 만드는 관점은 크게 두 가지다. 엔지니어 관점은 구체적인 사용 사례와 예측 가능성을 중시하고, 문제가 생기면 프롬프트에 지시를 추가해 행동을 고치려 한다. 멘토 관점은 에이전트가 무엇을 알고 무엇이 부족한지 살피며, 문제가 생기면 더 잘 지원할 방법을 찾는다.

처음에는 지시를 추가하는 방식도 효과가 있지만, 에이전트가 스스로 처리할 일이 많아지면 지시가 쌓이고 서로 모순될 수 있다. 그 결과 지시가 다루지 않는 상황에서도 에이전트의 수행이 나빠질 수 있다. 글쓴이는 규칙을 없애자는 뜻은 아니라고 설명한다. 에이전트가 무엇을 읽고 바꾸고 보낼 수 있는지는 중요하지만, 이런 제한은 프롬프트보다 권한·샌드박스·검사 같은 환경에 두는 편이 낫다는 견해다. 그러면 프롬프트와 문서는 설명에 집중할 수 있다. 앤스로픽의 프롬프트 작성 지침도 지시의 동기를 설명하고, 하지 말라는 말보다 대신 할 일을 알려 주도록 권한다.

에이전트용 문서는 모든 단계를 나열하기보다 맥락과 지침을 중심으로 쓴다. 무엇을 만들고 있는지, 왜 중요한지, 어떤 방식이 효과적이었는지를 설명하면 미리 열거할 수 없는 예외 상황에도 적용할 여지가 생긴다. 구체적인 지시와 예시는 쓸 수 있지만, 글쓴이의 경험상 예시를 늘리는 것보다 상위 수준의 설명을 개선하는 편이 더 도움이 되는 경우가 많다.

문서에는 조언의 이유와 결과를 함께 적는 것이 좋다. 예를 들어 공개 API를 바꾸지 말라고만 하기보다, 다른 팀이 패키지를 가져다 쓰므로 함수 서명을 바꾸면 업그레이드 전까지 빌드가 깨진다고 설명하면 에이전트가 내부 함수 변경과 호환성 변경의 차이도 판단할 수 있다. 조언을 사실처럼 적는 것도 피해야 한다. “테스트는 적게 둔다”는 규칙인지 관찰인지 불분명하지만, 경계에 테스트를 몇 개 두는 방식으로 대부분의 버그를 잡았다고 쓰면 경험에 근거한 조언임을 알 수 있다. 문서는 내용을 한 줄씩 덧대기보다 전체를 다시 써야 일관성을 유지하기 쉽다.

코드베이스에 남길 정보

에이전트는 프로젝트를 시작하는 일에는 능숙하지만, 세션이 바뀌면 이전 작업의 기억 없이 시작한다. 아키텍처를 선택한 이유, 검토했다가 버린 대안, 팀의 작업 방식처럼 코드·테스트·README·API 문서에 담기지 않은 정보도 저장소에 기록해야 한다. 글쓴이는 회의록도 별도 도구에 두기보다 코드베이스에 보관한다고 설명한다.

저장소에는 프로젝트의 목적과 대상, 구성 요소의 관계와 현재 상태를 설명하는 개요를 둔다. 이후 작업을 제약하는 결정은 날짜, 선택한 내용, 이유, 제외한 대안을 짧게 기록한다. 팀의 작업 절차와 무엇을 좋은 결과로 보는지도 적는다. 팀의 취향을 문서화하기는 어렵지만, “GOV.UK 스타일 가이드에 맞춰 작성하라”처럼 기존 지침을 참조하거나, 복잡성은 필요성을 입증해야 한다는 식으로 짧고 의미가 분명한 문장을 활용할 수 있다.

글쓴이는 작업을 나누는 리드 에이전트가 각 작업마다 새 에이전트를 시작하게 한다. 작은 변경이 아닌 작업은 저장소 정보만 보고 검토할 새 에이전트도 둔다. 긴 착수 문서보다 짧고 개괄적인 작업 설명이 더 잘 작동했다고 말한다. 새 에이전트는 이전 세션에서 구두로만 전달된 정보를 갖고 있지 않으므로, 검토에서 놓친 문제는 문서의 빈틈을 찾아 고치는 계기가 된다. 작업이 끝날 때마다 무엇이 지연을 일으켰고 문서에서 무엇이 잘못되거나 빠졌는지 짧게 기록하면 절차를 개선할 수 있다.

새 저장소에 복사해 쓸 기본 문서는 gist에 공개돼 있다.

  • 1-writing.md: 에이전트용 문서·프롬프트·작업 설명 작성법
  • 2-AGENTS.md: 매 세션이 가장 먼저 읽는 진입 문서
  • 3-ways-of-working.md: 작업을 수행하는 절차
  • 4-leading.md: 리드가 작업을 배정하고 검토하며 개선하는 방법

이 문서는 처음부터 시작하는 프로젝트를 위한 기본 틀이며, 복사한 시점에 모든 문장이 참이도록 작성됐다. CLAUDE.md에서 AGENTS.md를 가리키게 하고, 프로젝트 개요나 결정 기록처럼 나머지 문서는 필요에 따라 에이전트가 작성하도록 할 수 있다. 목표는 별도의 맥락을 전달받지 않은 새 에이전트도 작업과 검토를 해낼 수 있는 저장소를 만드는 것이다.

CodeWords와 Jack & Jill에서 에이전트를 구축해 온 경험을 바탕으로 한 연재의 첫 글이다. 다음 글에서는 지식 노동 에이전트의 하네스와 에이전트가 실행되는 환경을 감독하는 방법을 다룰 계획이다.