저장소 128개에 코딩 에이전트의 입구를 만든 기록

한 소비자 앱 회사의 저장소 128개에 코딩 에이전트가 처음 읽을 "입구" 문서를 같은 규칙으로 만들어 넣었습니다. 필수 문서 네 개를 정하고, 규칙을 어기면 실패하는 검사기로 확인하고, 기본 브랜치는 건드리지 않았습니다. 활성 저장소 37개는 첫 검사 기준을 문제 없이 통과했습니다. 에이전트 성능이 실제로 좋아졌는지는 아직 재지 않았습니다.

문제: 에이전트는 매번 처음부터 헤맨다

오래된 회사의 저장소는 대개 사람의 기억으로 굴러갑니다. 어떤 폴더가 중요한지, 어떤 서비스가 어디를 부르는지, 배포는 어떻게 하는지가 문서보다 사람 머리에 있습니다. 사람은 옆자리에 물어보면 되지만, 코딩 에이전트는 매 세션을 빈손으로 시작합니다. 그래서 첫 몇 턴을 파일을 여기저기 열어 보는 데 씁니다.

목표는 이 첫 몇 턴을 줄이는 것이었습니다. 에이전트가 저장소에 들어오면 무엇을 먼저 읽어야 하는지 알려 주는 입구를 모든 저장소에 같은 모양으로 두는 것이죠.

만든 것

• 대상: 저장소 128개. 활동 정도에 따라 세 등급(37·38·53개)으로 나눴습니다.
• 필수 산출물 네 개: README.md, AGENTS.md, structure/INDEX.md, structure/manifest.json.
• 작업 방식: 기본 브랜치는 건드리지 않고 별도 브랜치에 올렸습니다. 원격 저장소에 파일이 실제로 있는지 확인하지 못하면 성공으로 치지 않는 fail-closed 검사를 기본으로 했습니다.

검사한 것

문서를 쓰는 것보다 “규칙대로 들어갔는지” 확인하는 쪽이 더 중요했습니다. 검사기를 따로 만들어 활성 저장소 37개에 돌렸고, 첫 번째 사양 기준으로 문제 0건이 나왔습니다. 원격 브랜치와 로컬의 차이가 없는 것도 함께 확인했습니다.

그 직후 사양을 한 번 더 조였습니다. “바로 시작하기” 절을 두 번째로 올리고, 먼저 읽을 파일을 세 개로 정하고, 설계 결정은 최대 일곱 개로 줄였습니다. 돌아보면 첫 사양은 검사하는 사람이 보기 편한 문서였고, 두 번째 사양은 읽는 에이전트의 첫 턴 비용을 줄이는 문서입니다.

아직 증명하지 못한 것

솔직하게 적어 둡니다.

• 강화된 두 번째 사양으로는 아직 전체를 다시 검사하지 않았습니다.
• 활동이 적은 나머지 저장소들의 현재 상태는 이번 검사 범위 밖이었습니다.
• 가장 중요한 질문, “에이전트가 이 입구 덕분에 첫 턴에 맞는 파일을 여는가”는 아직 측정 전입니다.

다음 단계는 같은 작업 5~10건을 입구 문서가 있는 브랜치와 없는 브랜치에서 돌려, 첫 턴에 연 파일, 성공률, 수정 횟수, 잘못 건드린 파일 수를 비교하는 것입니다. 결과가 나오면 이 글에 덧붙이겠습니다.

배운 것

AX는 도구를 설치하는 일보다 “에이전트가 일할 수 있는 지형”을 만드는 일에 가깝습니다. 그리고 그 지형이 제대로 깔렸는지는 문서가 아니라 검사기로 확인해야 합니다. 이 작업의 계획과 검증도 codexclaw의 계획·감사·확인 루프로 돌렸습니다.