요약 (TL;DR) — 다섯 개의 포스트. 하나의 파일. 전체적인 흐름: 그것이 무엇인가 → 하나 작성하기 → 왜 부패하는가 → 진실성 유지하기 → 사실로부터 작성하기. 이것이 마무리입니다: 시리즈의 지도, 다섯 가지 FAQ, 그리고 가장 기억에 남는 교훈 — 사실의 블록화 vs 독특한 산문 (facts block vs unique prose).

📚 AGENTS.md 시리즈 · 당신은 Part 6 — 시리즈 마무리에 있습니다.

1. I · 가이드북 (field guide)
2. II · 실습 (hands-on)
3. III · 노후화 (stale)
4. IV · 진실성 유지하기 (keep it true)
5. V · 사실로부터 (from facts)
6. VI · 시리즈 마무리 — 당신은 여기에 있습니다

처음 오셨나요? AGENTS.md는 리포지토리(repo) 루트에 있는 단일 Markdown 파일로, AI 코딩 에이전트(AI coding agents)에게 명령(commands), 테스트(tests), 컨벤션(conventions), 가드레일(guardrails) 등 해당 환경에서 어떻게 작업해야 하는지를 알려줍니다. AAIF / Linux Foundation 산하의 공개 표준(Open standard)입니다. 전체 과정을 확인하고 싶다면 Part I부터 시작하세요.

우리가 다룬 내용

다섯 가지 교훈. 하나의 목표: 브리핑 에이전트가 **진실 (true)**을 따르게 만드는 것.

이 마무리 글 외에 딱 하나만 읽어야 한다면: 부패(rot)를 느껴본 적이 없다면 III을; 이미 파일이 있고 그것이 거짓말을 하는 것을 멈추고 싶다면 V를 읽으세요.

단계별 살펴보기: 흐름이 어떻게 연결되는가

다섯 개의 섬이 아니라, 하나의 경로로 읽으세요.

I   AGENTS.md란 무엇인가?          →  원칙, 형태, 안티 패턴 (anti-patterns)
II  작성하기                   →  실제 파일, 실제 에이전트의 이점
III 정보가 오래되는 현상 관찰           →  왜 "현재"가 "진실"과 같지 않은가
...

I과 II는 실제로 작동하는 파일을 얻게 해줍니다.

III과 IV는 변화 속에서도 정직함을 유지하는 파일을 얻게 해줍니다.

V는 수동으로 입력해서는 안 되었을 코드 라인들의 부류를 제거합니다.

VI (현재 단계)는 지도이자 판단의 영역입니다: 무엇이 여전히 인간을 필요로 하는가.

이 시리즈는 AGENTS.md를 더 길게 작성하라고 주장하는 것이 아닙니다. 더 진실된 것을 작성하라고 주장합니다: 간결한 사실 블록 (facts block), 그 다음은 당신의 산문 (prose). 전체 길이는 당신의 결정에 달려 있습니다.

다섯 가지 FAQ

1. 이미 README / CONTRIBUTING / CLAUDE.md가 있다면 AGENTS.md가 필요한가요?

네, 에이전트가 저장소(repo) 내에서 작동한다면 필요합니다. README는 브라우징하는 인간을 위한 것입니다. CONTRIBUTING은 프로세스입니다. 벤더 파일 (CLAUDE.md 등)은 특정 도구에 종속적입니다. AGENTS.md는 많은 에이전트가 이미 찾고 있는 **도구 불가지론적 브리핑 (tool-agnostic briefing)**입니다. 짧게 유지하고, 깊이 있는 내용은 링크로 연결하세요. 소설처럼 중복해서 작성하지 마세요.

2. 길이는 어느 정도가 적당한가요?

에이전트(그리고 인간)가 모든 라인을 여전히 신뢰할 수 있을 만큼 충분히 짧아야 합니다. 실행 가능한 명령, 존재하는 경로, 그리고 **실질적인 가드레일 (guardrails)**을 선호하세요. 특정 섹션이 트리(tree) 구조나 한 줄짜리 규칙으로 검증될 수 없다면, 삭제하거나 옮기세요.

3. 가장 흔한 실패 모드는 무엇인가요?

여전히 공식적인 것처럼 보이지만 오래된 정보 (Stale truth)입니다. 이름이 바뀐 스크립트, 작동하지 않는 테스트 명령, 트리 구조보다 뒤처진 구조 지도 — 에이전트는 이를 전적인 신뢰를 가지고 따릅니다. Part III가 바로 이 지점을 다루는 핵심입니다. 최신성(Freshness)은 부수적인 것이 아니라, 그 자체가 결과물입니다.

4. 모든 라인을 자동 생성해야 하나요?

아니요. 저장소가 증명할 수 있는 것들을 생성(또는 확인)하세요: 패키지 이름, 스크립트, 레이아웃, CI 명령. 인간의 영역으로 남겨두어야 할 것들: 판단, 제품의 "이유 (why)", 트리에 나타나지 않는 팀 규범, 아직 린터 (linter) 규칙이 되지 않은 "X를 절대 하지 마시오" 등. Part V는 사실 (facts) 부분의 최종 단계이지, 판단력을 대체하는 것이 아닙니다.

5. 아무것도 없다면 어디서부터 시작해야 하나요?

1. Part I — shape and anti-patterns
2. Part II — write one and verify with an agent
3. When it starts lying, IV then V

III를 영원히 건너뛰지 마세요 — 힘든 방식으로 만나게 될 겁니다.

저의 교훈: facts 블록 대 고유한 산문(prose)

만약 이 시리즈가 하나의 아이디어를 남긴다면, 그것은 이것이어야 합니다.

저는 이 파일 전체를

이 포스트에 댓글을 남기거나, 당신이 아끼는 프로젝트(예를 들어, 해당 리포지토리(repo)의 구조를 crates/ / src/와 일치하도록 유지하는 것 등)에 대한 논의를 시작해 보세요. 실제 트리(trees)가 보기 좋은 문서(docs)에 맞서 목소리를 낼 때 표준은 더 발전합니다.

시리즈 인덱스 (북마크해 두세요)

1. AGENTS.md: AI 코딩 에이전트를 실제로 유용하게 만드는 단 하나의 파일 — 현장 가이드 (field guide)
2. AGENTS.md 실습: 단계별로 구축하기 — 튜토리얼 (tutorial)
3. 당신의 AGENTS.md는 이미 오래되었습니다 (그리고 당신의 에이전트는 그것을 완전히 신뢰합니다) — 위협 (the threat)
4. AGENTS.md의 정확성 유지: 단계별로 부패를 막는 법 — 규율 (discipline)
5. 사실로부터의 AGENTS.md: 변질되지 않는 파일 작성하기 — 최종 도구 경로 (endgame tool path)
6. 이 포스트 — 마무리 · FAQ · 사실(facts) 대 산문(prose)

추가 읽을거리: agents.md에 있는 표준 자체, 그리고 faf.one/agents에 있는 섹션별 현장 가이드 — 어떤 내용이 한 줄을 차지할 가치가 있는지, 순서, 길이, 안티 패턴(anti-patterns) 등에 대해 확인해 보세요.

시리즈를 읽어주셔서 감사합니다.
짧고 진실된 파일을 배포하세요.
그리고 그 진실함을 유지하세요.
👍