AI에게 필요한 건 설명서가 아니라 지도였다

AI는 프로젝트를 모른다

AI는 코드를 잘 쓰지만 우리 프로젝트의 맥락은 모른다. 어떤 구조로 되어 있는지, 어떤 규칙을 지켜야 하는지는 코드만 봐서는 알기 어렵다. 그래서 저장소 안에 Markdown으로 지식베이스를 만들어 두고 Agent가 읽게 했다.

Microsoft도 저장소에 Agent를 처음 도입할 때 Markdown 지식베이스부터 만들라고 권한다.

When you first start using an agent in your repo, you'll notice long sessions with higher failure rates. Start by prompting the agent to populate the knowledge base of Markdown files about your repo, verify the output to ensure correctness, and then set up a continuous improvement agent so that knowledge base memory is updated after each agent session. Things start to compound rapidly.

저장소에서 에이전트를 처음 쓰기 시작하면 세션이 길어지고 실패율도 높아진다. 먼저 에이전트에게 저장소에 대한 Markdown 지식베이스를 채우게 하고 결과가 정확한지 검증한 다음, 에이전트 세션이 끝날 때마다 지식베이스가 갱신되도록 지속 개선 에이전트를 설정하라. 그러면 효과가 빠르게 쌓이기 시작한다.

출처: Jay Parikh, Introducing Command Line, and the new rules for builders

많이 알려 줄수록 좋을까 ?

나는 뭐든 많으면 좋다고 생각했다. 규칙이든 도구든 많이 알려 줄수록 AI가 더 잘할 거라고 믿었다. 그런데 AGENTS.md가 길어져도 결과물은 나아지지 않았다.

OpenAI: 거대한 AGENTS.md는 실패했다

OpenAI Codex 팀도 모든 정보를 하나의 거대한 AGENTS.md에 담는 방식을 실제로 시도했다가 실패했다고 한다.

• 자리를 밀어낸다: Context는 한정된 자원이라 긴 지침이 현재 작업과 실제 코드, 관련 문서가 쓸 공간을 차지한다.
• 중요한 게 흐려진다: 모든 지침이 중요하다고 하면 무엇이 정말 중요한지 구분하기 어렵다.
• 낡은 규칙이 쌓인다: 하나의 문서에 계속 더하다 보면 오래된 규칙이 그대로 남는다.
• 검증하기 어렵다: 문서가 크고 하나로 뭉쳐 있으면 최신인지, 다른 문서와 맞는지 확인하기 어렵다.

그래서 OpenAI가 내린 원칙은 간단하다.

give Codex a map, not a 1,000-page instruction manual.

Codex에게 1,000페이지짜리 설명서가 아니라 지도를 줘라.

OpenAI는 약 100줄짜리 짧은 AGENTS.md만 기본 Context로 주고 자세한 지식은 구조화된 docs/ 디렉터리에 둔다. AGENTS.md는 지식 그 자체가 아니라 필요한 지식이 어디 있는지 알려 주는 목차 역할을 한다. Agent는 처음부터 모든 정보를 싣지 않고 작업하면서 필요한 문서를 찾아간다.

출처: OpenAI, Harness engineering: leveraging Codex in an agent-first world

Anthropic: Context에도 예산이 있다

Anthropic도 비슷한 방향을 제안한다. Anthropic은 Context를 중요하지만 유한한 자원(critical but finite resource)으로 본다.

• 많이 읽을 수 있어도 다 주는 게 답은 아니다: 최근 모델은 한 번에 읽을 수 있는 분량(Context Window)이 크게 늘었다. 그래도 글이 길어질수록 모든 부분에 똑같이 집중하기 어렵고, 쓸모없는 정보가 섞이면 중요한 정보에 가야 할 집중이 흩어진다. 집중력에도 쓸 수 있는 양이 정해져 있다는 뜻에서 Anthropic은 이를 Attention Budget이라고 부른다.
• 결과에 도움이 되는 정보만 골라 준다: 원하는 결과를 얻는 데 실제로 쓰이는 정보는 남기고 쓰이지 않는 정보는 뺀다. Anthropic은 이렇게 골라낸 핵심 정보를 high-signal token이라고 부른다.
• 최소한이 짧다는 뜻은 아니다: 필요한 정보는 충분히 주되 관련 없는 규칙, 중복 설명, 수많은 Edge Case를 미리 다 넣지는 않는다.

Claude Code도 이 원칙을 따른다. 프로젝트 전반에 필요한 정보는 CLAUDE.md로 처음부터 주고 나머지 파일은 작업 중 필요할 때 찾아 읽는다.

출처: Anthropic, Effective context engineering for AI agents

설명서 대신 지도를 만든다

그래서 AGENTS.md를 지도로 바꿨다. 아래는 구조를 보여 주는 예시다.

repository/
├── AGENTS.md          ← Agent가 항상 읽는 지도
├── README.md
├── docs/
│   ├── architecture/
│   │   ├── overview.md
│   │   ├── database.md
│   │   ├── redis.md
│   │   └── messaging.md
│   ├── domain/
│   │   ├── member.md
│   │   ├── asset.md
│   │   └── location.md
│   ├── development/
│   │   ├── coding-convention.md
│   │   ├── testing.md
│   │   └── local-setup.md
│   └── operations/
│       ├── deployment.md
│       └── troubleshooting.md
└── src/

AGENTS.md에는 필요한 문서가 어디 있는지만 적는다.

# Project

## Architecture

- 전체 구조: `docs/architecture/overview.md`
- Database: `docs/architecture/database.md`
- Redis: `docs/architecture/redis.md`
- Messaging: `docs/architecture/messaging.md`

## Domain

- 회원: `docs/domain/member.md`
- 자산: `docs/domain/asset.md`
- 위치: `docs/domain/location.md`

## Testing

- 테스트: `docs/development/testing.md`

지시는 줄이고, 피드백은 강하게 !

모델 성능이 좋아질수록 모델의 생각과 행동을 하나하나 지시하는 Harness는 얇아질 수 있다. 그렇다고 Harness가 덜 중요해지는 건 아니다. 오히려 Agent의 자율성이 높아질수록 모델이 올바르게 일하고 결과를 검증할 수 있게 해 주는 환경이 더 중요해진다.

좋은 Harness는 더 많이 통제하는 쪽이 아니라, 덜 간섭하고 피드백은 더 확실하게 주는 쪽으로 가야 한다.