Coding Agents Evolved. Our Repositories Didn’t.

개요

코딩 에이전트의 발전은 복잡한 다단계 소프트웨어 개발 작업을 자동화할 수 있게 했지만, 기존의 거대한 AGENTS.md 파일은 컨텍스트 낭비, 유지보수 어려움, AI 개발 효율성 저하 등의 문제를 야기합니다.

주요 내용

* 모놀리식 AGENTS.md의 한계:
* 수천 줄에 달하는 지침 파일은 프로젝트 아키텍처, 환경 설정, 코딩 표준, 테스트 전략 등 다양한 정보를 담고 있어 인간이 탐색하고 유지보수하기 어렵습니다.
* 에이전트가 모든 관련 없는 정보를 로드하여 실제 작업에 필요한 컨텍스트를 소비하고 토큰 사용량을 늘릴 수 있습니다.
* 다양한 종류의 정보(예: 아키텍처 규칙 vs. 빌드 명령)가 서로 다른 속도로 변경되므로 단일 파일로 관리하기 어렵습니다.
* 오래된 정보나 작동하지 않는 명령이 포함될 가능성이 있어 검증이 어렵습니다.
* OpenAI의 해결 방안:
* 거대한 AGENTS.md 대신 짧은 AGENTS.md를 목차로 사용하여 구조화된 저장소 지식 기반을 활용하는 방식으로 전환했습니다.
* 제안된 모듈식 저장소 하네스 구조:
* AGENTS.md를 단일 진입점으로 유지하고, 실제 저장소 지식은 .harness/와 같은 디렉토리 구조 내에 모듈화하여 저장합니다.
* 이 모듈은 아키텍처, 환경, 검증, 워크플로우 등 특정 기능별로 분리될 수 있습니다.
* 프로젝트 규모에 따라 모듈 구성이 달라질 수 있으며, 작은 프로젝트에서는 '검증' 모듈 안에 테스트 규칙이 포함될 수 있습니다.
* 점진적 컨텍스트 공개:
* 에이전트가 작업에 필요한 관련 컨텍스트만 로드하도록 하여 컨텍스트 효율성, 토큰 사용량, 지침 탐색 용이성, 인간 가독성, 문서 소유권, 에이전트 간 일관성을 개선합니다.
* 실행 가능한 지침의 중요성:
* 가능한 경우 Markdown 파일에만 의존하는 대신, scripts/test-unit과 같이 실행 가능하고 재현 가능한 명령을 노출하는 것이 좋습니다.
* Markdown은 사용 시점, 검증 내용, 실패 시 의미 등을 설명하고, 스크립트는 실제 실행 방식을 정의합니다.
* 구현 이전 단계 적용:
* 이 개념은 코딩 시작 전에도 적용될 수 있으며, 에이전트가 '준비된 정의(Definition of Ready)' 및 '완료된 정의(Definition of Done)'를 검증하는 데 사용될 수 있습니다.
* 실험 계획:
* 모놀리식 AGENTS.md와 모듈식 .harness/ 구조를 동일한 에이전트, 모델, 저장소, 작업, 검증 기준으로 비교하는 공개 실험을 시작합니다.
* 입력 토큰 수, 작업 성공률, 테스트 통과율, 실행 시간 등 다양한 지표를 측정하여 모듈식 컨텍스트가 구현 품질 저하 없이 효율성을 향상시키는지 평가할 예정입니다.

시사점

모듈화된 저장소 하네스 구조는 코딩 에이전트의 발전 속도에 맞춰 저장소 지식 관리를 혁신하여 AI 기반 개발의 확장성과 효율성을 크게 향상시킬 잠재력을 가지고 있습니다.