거대한 AGENTS.md 파일이 왜 컨텍스트 (context)를 낭비하고, 유지보수성을 해치며, AI 지원 개발의 확장을 어렵게 만드는지에 대하여.

몇 년 전, 많은 개발자에게 소프트웨어 개발을 위해 AI를 사용하는 것은 코드의 작은 조각을 채팅창에 복사하는 것을 의미했습니다.

우리는 리팩토링 (refactoring)을 요청하고, 응답을 다시 에디터로 복사하고, 직접 테스트를 실행한 뒤, 무언가 실패하면 다시 채팅으로 돌아갔습니다.

코딩 에이전트 (Coding agents)가 그 워크플로우 (workflow)를 바꾸어 놓았습니다.

Codex, Claude Code 등과 같은 도구들은 이제 전체 저장소 (repository)를 탐색하고, 여러 파일을 수정하며, 명령어를 실행하고, 테스트를 수행하며, 실패 시 반복 작업을 수행할 수 있습니다.

코딩 에이전트는 코드 어시스턴트 (code assistants)를 다단계 소프트웨어 개발 작업을 수행할 수 있는 도구로 탈바꿈시켰습니다.

하지만 대부분의 저장소는 이러한 새로운 종류의 기여자 (contributor)를 위해 설계되지 않았습니다.

저장소가 에이전트의 작업 컨텍스트 (working context)의 일부가 되다

코딩 에이전트에게는 소스 코드 그 이상의 것이 필요합니다.

에이전트는 다음과 같은 사항들을 이해해야 할 수도 있습니다:

• 프로젝트 아키텍처 (architecture)
• 의존성 경계 (dependency boundaries)
• 코딩 컨벤션 (coding conventions)
• 테스트 전략 (test strategy)
• 빌드 명령어 (build commands)
• 로컬 환경 요구사항 (local environment requirements)
• 검증 단계 (validation steps)
• 보안 제한 사항 (security restrictions)
• 완료 정의 (definition of done)

일반적인 해결책은 이러한 지침들을 AGENTS.md, CLAUDE.md 또는 기타 에이전트 전용 설정 파일과 같은 파일 안에 배치하는 것입니다.

이 방법은 효과가 있습니다.

저 또한 한동안 제 프로젝트에서 이와 유사한 작업을 해왔습니다.

하지만 저장소가 커짐에 따라 지침 파일도 함께 커집니다.

결국, 단일 파일이 서로 관련 없는 관심사들을 다루며 수천 줄에 달하게 될 수도 있습니다:

Architecture
Testing
Environment setup
...

그 시점에서 해당 파일은 더 이상 단순한 에이전트 지침 세트가 아닙니다.

그것은 비공식적인 저장소 운영 매뉴얼 (operating manual)이 되어버렸습니다.

모놀리식 컨텍스트 (monolithic context) 문제

거대한 AGENTS.md는 명백한 장점이 있습니다. 에이전트가 어디서 그것을 찾아야 하는지 알고 있다는 점입니다.

하지만 이는 또한 여러 가지 문제를 야기합니다.

인간이 탐색하기 어렵다

이 파일들은 에이전트만을 위한 것이 아닙니다.

개발자 또한 이 규칙들을 읽고, 검토하고, 유지 관리하며, 논의해야 합니다.

테스트를 변경하려는 사람이 멀티플레이어 아키텍처 (multiplayer architecture), 에셋 컨벤션 (asset conventions), 배포 규칙 (deployment rules), 그리고 UI 표준 (UI standards)을 모두 탐색해야 할 필요는 없습니다.

관련 없는 컨텍스트가 로드될 수 있음

도메인 클래스 (domain class)의 작은 버그를 수정하는 데 다음과 같은 정보는 필요하지 않을 수 있습니다:

• 운영 배포 (production deployment);
• UI 에셋 (UI assets);
• 데이터베이스 마이그레이션 (database migrations);
• 릴리스 절차 (release procedures);
• 외부 통합 (external integrations).

거대한 루트 지침 파일 (root instruction file)이 모든 태스크에 주입될 때, 관련 없는 가이드라인이 태스크, 코드, 그리고 관련 문서에 사용될 수 있는 컨텍스트 (context)를 소비할 수 있습니다.

서로 다른 지식은 서로 다른 속도로 변화함

아키텍처 규칙 (Architecture rules)은 몇 달 동안 안정적으로 유지될 수 있습니다.

부트스트랩 명령 (Bootstrap commands)은 툴체인 (toolchain) 업데이트 후에 변경될 수 있습니다.

검증 규칙 (Validation rules)은 매주 진화할 수 있습니다.

이 모든 것을 하나의 문서에 담아두는 것은 소유권 관리와 유지 관리를 더 어렵게 만듭니다.

파일 검증이 어려워짐

거대한 마크다운 (Markdown) 문서는 대부분 수동적인 가이드라인입니다.

더 이상 작동하지 않는 명령, 더 이상 존재하지 않는 경로, 또는 현재 코드베이스 (codebase)와 모순되는 규칙을 설명할 수도 있습니다.

이 문제는 완전히 이론적인 것만이 아닙니다.

OpenAI는 거대한 AGENTS.md 파일이 컨텍스트를 소비하고, 유지 관리가 어려우며, 기계적으로 검증하기 힘들다는 이유로 이를 지양한다고 공개적으로 밝혔습니다.

그들의 해결책은 구조화된 저장소 지식 베이스 (repository knowledge base)의 목차 역할을 하는 더 짧은 AGENTS.md를 사용하는 것이었습니다.

그러한 경험은 이 실험의 방향성을 뒷받침하지만, 한 가지 중요한 질문을 남깁니다:

이 접근 방식이 벤더 중립적 (vendor-neutral)이고, 재사용 가능하며, 측정 가능한 저장소 사양 (repository specification)이 될 수 있을까요?

저장소 하네스 (A repository harness)

저는 OpenAI가 설명한 방향에 동의합니다. AGENTS.md가 저장소의 전체 운영 모델을 포함해서는 안 됩니다.

상세한 지식은 모듈화되고 버전 관리되는 저장소 구조 내에 존재해야 하며, AGENTS.md는 진입점 (entry point) 역할을 해야 합니다.

작은 부트로더 (bootloader)처럼 말이죠.

실제 저장소 지식 (repository knowledge)은 버전 관리(versioned)가 가능하고 모듈화된 (modular) 구조로 존재할 수 있습니다:

AGENTS.md
    ↓
.harness/
...

.harness 디렉토리는 제안된 컨벤션 (convention)이며, 코딩 에이전트 (coding agents)가 현재 자동으로 이해할 수 있는 것은 아닙니다.

첫 번째 버전에서는 AGENTS.md가 지원되는 진입점 (entry point)으로 유지되며, 에이전트에게 저장소 하네스 (repository harness)를 어떻게 발견하고 사용하는지 지시하게 됩니다.

정확한 파일 이름은 이 단계에서는 의도적으로 정의되지 않았습니다.

예를 들어, 작은 프로젝트에서는 테스트 (testing)가 검증 (validation)의 일부가 될 수 있습니다:

validation/
└── 테스트 규칙 및 명령 (testing rules and commands)

더 큰 프로젝트는 다음과 같은 내용을 포함하는 전용 테스트 문서가 필요할 수 있습니다:

• 유닛 테스트 (unit tests)를 사용하는 시점;
• 통합 테스트 (integration tests)를 사용하는 시점;
• 각 스위트 (suite)를 실행하는 방법;
• 모킹 (mocking) 및 페이크 (fake) 컨벤션;
• 테스트 명명 표준 (test naming standards);
• 새로운 테스트를 작성하기 위한 패턴 (patterns).

목표는 모든 저장소를 동일한 디렉토리 트리 (directory tree)로 강제하는 것이 아닙니다.

목표는 에이전트가 발견할 수 있는 능력 (capabilities)을 정의하는 것입니다.

저장소 컨텍스트의 점진적 공개 (Progressive disclosure of repository context)

모듈형 하네스 (modular harness)를 사용하면, 도메인 버그 (domain bug)를 작업하는 에이전트는 다음과 같은 내용을 로드할 수 있습니다:

Architecture (아키텍처)
Testing (테스트)
Validation (검증)

프로젝트를 처음으로 준비하는 에이전트는 다음과 같은 내용을 로드할 수 있습니다:

Bootstrap (부트스트랩)
Environment (환경)
Validation (검증)

배포 (deployment)와 관련된 작업은 완전히 다른 세트를 로드할 수도 있습니다.

이는 일종의 점진적 컨텍스트 로딩 (progressive context loading)을 생성합니다:

저장소 핸드북 (repository handbook) 전체를 제공하는 대신, 현재 작업에 필요한 컨텍스트 (context)를 에이전트에게 제공하십시오.

이 접근 방식은 잠재적으로 다음과 같은 사항을 개선할 수 있습니다:

• 컨텍스트 효율성 (context efficiency);
• 토큰 사용량 (token usage);
• 지시 사항 발견 가능성 (instruction discoverability);
• 인간 가독성 (human readability);
• 문서 소유권 (documentation ownership);
• 서로 다른 코딩 에이전트 간의 일관성 (consistency).

하지만 이것은 아직 가설 (hypothesis) 단계입니다.

문서는 충분하지 않다

유용한 저장소 하네스 (repository harness)가 마크다운 (Markdown) 파일로만 구성되어서는 안 됩니다.

가능한 한, 지시 사항은 실행 가능하고 재현 가능한 작업 (executable and reproducible operations)을 가리켜야 합니다.

긴 테스트 명령 시퀀스를 문서화하는 대신, 저장소는 다음과 같은 것을 노출할 수 있습니다:

./scripts/test-unit
./scripts/test-integration
./scripts/validate

Markdown은 다음 사항을 설명합니다:

• 명령어를 언제 사용해야 하는지;
• 무엇을 검증하는지;
• 실패가 무엇을 의미하는지;
• 어떤 예외가 허용되는지.

스크립트는 작업이 어떻게 수행되는지를 정의합니다.

이를 통해 저장소는 CI를 통해 검증하기가 더 쉬워지며, 에이전트가 일련의 명령어 시퀀스를 정확하게 재현해야 하는 의존성도 줄어듭니다.

구현 작업 그 이상

동일한 개념이 결국 코딩이 시작되기 전에도 적용될 수 있습니다.

Jira, GitHub Issues, Linear, Azure DevOps, 또는 다른 이슈 트래커나 내부 제품 백로그 (product backlog)를 사용하는 팀은 저장소별 준비 완료 정의 (Definition of Ready)를 정의할 수 있습니다.

작업이 구현 파이프라인 (implementation pipeline)에 진입하기 전에, 에이전트는 다음 사항을 확인할 수 있습니다:

• 수락 기준 (acceptance criteria)이 명확한지;
• 필요한 아키텍처 컨텍스트 (architectural context)가 존재하는지;
• 의존성 (dependencies)이 식별되었는지;
• 작업이 기존 문서와 충돌하는지;
• 예상되는 검증 (validation)이 정의되었는지;
• 중요한 정보가 누락되었는지.

또한 팀은 구현이 시작되기 전에 합의된 완료 정의 (Definition of Done)를 저장소 하네스 (repository harness)에 인코딩할 수 있습니다.

구현 중 및 구현 후에, 에이전트는 해당 정의를 사용하여 작업을 완료된 것으로 간주하기 전에 어떤 테스트, 검증, 리뷰, 문서 업데이트 및 수동 점검이 필요한지 결정할 수 있습니다.

실험

저는 Repository Harness Specification이라는 오픈 프로젝트를 시작합니다.

첫 번째 목표는 동일한 저장소의 두 가지 버전을 비교하는 것입니다:

모놀리식 (Monolithic)

AGENTS.md

모든 지침이 하나의 커다란 파일에 포함되어 있습니다.

모듈형 (Modular)

AGENTS.md
.harness/

동일한 정보가 에이전트가 필요에 따라 발견하고 로드할 수 있는 작업 관련 모듈로 구성됩니다.

저는 다음의 동일한 요소들을 사용하여 두 접근 방식을 평가할 계획입니다:

• 코딩 에이전트 (coding agent);
• 모델 (model);
• 저장소 (repository);
• 시작 커밋 (starting commit);
• 구현 작업 (implementation task);
• 검증 기준 (validation criteria).

이 실험은 토큰 소비량 그 이상을 측정할 것입니다.

가능한 지표에는 다음이 포함됩니다:

• 선택된 에이전트 또는 런타임 (runtime)에 의해 노출되는 입력 토큰 (input tokens);
• 사용 가능한 경우, 캐시된 (cached) 입력 토큰 및 캐시되지 않은 (uncached) 입력 토큰;
• 작업 성공률 (task success rate);
• 통과된 테스트 (tests passed);
• 검증 실패 (validation failures);
• 예상 범위를 벗어나 변경된 파일들;
• 수정 사이클 (correction cycles) 횟수;
• 실행 시간 (execution time).

에이전트가 더 나쁜 코드를 생성한다면 토큰을 줄이는 것은 유용하지 않습니다.

진정한 목표는 모듈형 저장소 컨텍스트 (modular repository context)가 구현 품질을 저하시키지 않으면서 효율성을 개선할 수 있는지 여부를 결정하는 것입니다.

공개 개발 (Building it in public)

이 프로젝트는 공개적으로 개발될 것입니다.

다음 단계는 다음과 같습니다:

1. 최소 저장소 하네스 (repository harness) 정의;
2. 실제 프로젝트를 수동으로 마이그레이션;
3. 재현 가능한 벤치마크 태스크 (benchmark tasks) 생성;
4. 모놀리식 (monolithic) 컨텍스트와 모듈형 (modular) 컨텍스트 비교;
5. 결과 발표;
6. 저장소 하네스를 초기화하고 검증하기 위한 CLI 구축;
7. 다양한 코딩 에이전트와의 통합 탐색.

이 글에서 제시된 구조는 최종 사양 (specification)이 아닙니다.

이것은 첫 번째 실험입니다.

코딩 에이전트는 빠르게 진화하고 있습니다.

이제 우리는 저장소가 에이전트와 함께 어떻게 진화해야 하는지 이해해야 합니다.

프로젝트는 다음에서 확인할 수 있습니다:

Repository Harness Specification

https://github.com/Repository-Harness-Specification

피드백, 비판, 그리고 기여를 환영합니다.