현장 가이드에서 저는 AGENTS.md가 무엇인지, 그리고 그 안에 무엇이 포함되어야 하는지를 다루었습니다. 이번에는 실습 후속편입니다. 실제 프로젝트를 위해 완전한 AGENTS.md를 한 섹션씩 구축해 보고, AI 코딩 에이전트(AI coding agent)를 지정하여 그것이 어떤 차이를 만들어내는지 지켜볼 것입니다. 마지막에는 여러분은 실제로 작동하는 파일을 갖게 될 것이며, 그 효과를 직접 확인하게 될 것입니다.

AGENTS.md가 처음이신가요? 이는 리포지토리(repo) 루트에 있는 단일 Markdown 파일로, AI 코딩 에이전트에게 빌드 단계, 테스트, 컨벤션(conventions), 가드레일(guardrails) 등 해당 리포지토리에서 어떻게 작업해야 하는지를 알려줍니다. 각 섹션 뒤에 숨겨진 "이유"는 현장 가이드에 설명되어 있습니다.

사용할 프로젝트

우리는 작지만 실제적인 서비스인 Python 기반 URL 단축기 API — FastAPI, SQLite, pytest를 위한 AGENTS.md를 작성할 것입니다. 몇 개의 엔드포인트(endpoints), 얇은 데이터 레이어(data layer), 테스트 스위트(test suite)로 구성됩니다. 이 프로젝트를 따라오거나, 여러분의 리포지토리로 교체하여 진행해도 됩니다 — 단계는 동일합니다.

구조:

linkshort/
  app/
    main.py        # FastAPI routes
...

Step 0 — 빈 파일로 시작하기

리포지토리 루트에서:

touch AGENTS.md

이것이 단계의 전부입니다. 우리는 에이전트가 30초 안에 읽을 수 있는 파일을 목표로, 한 번에 한 섹션씩 채워 나갈 것입니다.

Step 1 — 오리엔테이션(Orientation): 한 줄 작성

에이전트에게 무엇을 보고 있는지 알려주세요. 다음을 추가합니다:

# AGENTS.md

A URL shortener API in Python — FastAPI, SQLite, pytest.

한 문장만으로 에이전트의 사전 지식(priors)을 설정할 수 있습니다. 에이전트는 코드 한 줄을 읽기 전에 언어, 프레임워크, 저장소(storage)를 알게 됩니다.

Step 2 — 설정 및 실행 (Setup and run)

에이전트가 프로젝트를 시작할 수 없다면 도움을 줄 수 없습니다. 실제로 복사해서 붙여넣을 수 있는 명령어를 추가하세요:

## Setup
python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
...

플레이스홀더(placeholders)를 사용하지 말고, 여러분의 리포지토리에서 실제로 작동하는 명령어를 사용하세요.

Step 3 — 테스트: 에이전트의 피드백 루프 (Tests: the agent's feedback loop)

이 섹션이 가장 중요합니다. 테스트는 에이전트가 자신의 작업물을 스스로 확인하는 방법이기 때문입니다. 다음을 추가하세요:

## Test — 모든 테스트를 통과해야 변경 사항이 적용됨
pytest
ruff check .
...

이제 에이전트는 변경 사항을 검증하는 방법과 자신이 통과해야 할 기준을 알게 됩니다. pytest를 아는 에이전트는 이를 실행할 것이지만, 모르는 에이전트는 망가진 브랜치(broken branch)를 당신에게 넘겨줄 것입니다.

Step 4 — 지도: 파일들의 위치 (The map: where things live)

에이전트가 전체 트리 구조를 일일이 탐색(spelunking)하지 않고도 길을 찾을 수 있도록 짧은 지도를 제공합니다:

## Structure
- app/main.py    라우트 핸들러 (route handlers)
- app/db.py      SQLite 액세스 (매개변수화된 쿼리(parameterized queries)만 사용, 절대 문자열로 SQL을 생성하지 말 것)
...

관련된 위치에 바로 컨벤션(convention, "매개변수화된 쿼리만 사용")과 가드레일(guardrail, "직접 수정 금지")을 슬쩍 끼워 넣고 있다는 점에 주목하세요.

Step 5 — 컨벤션: 스타일 가이드 (Conventions: the house style)

당신이 따르기를 원하는 패턴들입니다. 구체적이어야 합니다. 모호한 규칙은 노이즈(noise)일 뿐입니다:

## Conventions
- 라우트 경계(route boundary)에서 Pydantic 모델을 사용하여 모든 입력을 검증할 것.
- 클라이언트 에러 발생 시 HTTPException을 발생시킬 것; 실패 시 절대 가공되지 않은 딕셔너리(raw dicts)를 반환하지 말 것.
...

"모든 것에 타입을 지정할 것; mypy가 깨끗하게 유지되어야 함"은 에이전트에게 정확히 무엇을 해야 할지 알려줍니다. 반면 "좋은 코드를 작성하라"는 알려주지 못합니다.

Step 6 — 커밋 및 PR (Commits and PRs)

에이전트가 PR(Pull Request)을 생성한다면, 내부 규칙을 제공하세요:

## Commits & PRs
- Conventional Commits (feat:, fix:, chore:).
- PR당 하나의 논리적 변경 사항만 포함할 것; CHANGELOG.md를 업데이트할 것.

Step 7 — 가드레일: 지뢰 (Guardrails: the landmines)

비싼 실수를 방지하기 위한 "하지 말아야 할 것(don'ts)"입니다:

## Don't
- 마이그레이션(migrations/)을 직접 수정하지 말 것 — 자동 생성되는 것입니다.
- main 브랜치에 직접 커밋하지 말 것 — 브랜치를 생성하고 PR을 올릴 것.
...

완성된 AGENTS.md

모두 합치면 복사해서 바로 사용할 수 있는 완전한 파일이 됩니다:

# AGENTS.md

Python으로 작성된 URL 단축기 API — FastAPI, SQLite, pytest.
...

읽는 데 30초면 충분합니다. 이제 실제로 작동하는지 확인해 봅시다.

Step 8 — 증명하기: 에이전트에게 실행시키기 (Prove it: point an agent at it)

이 부분이 핵심입니다. AI 코딩 에이전트(Claude Code, Cursor, Codex 등 당신이 사용하는 무엇이든)로 리포지토리를 열고, 실제 작업을 부여하세요:

"링크를 삭제하는 DELETE /links/{code} 엔드포인트를 추가하고, 테스트를 작성하세요."

AGENTS.md가 있는 상태에서 에이전트가 어떻게 동작하는지 지켜보세요:

• 먼저 파일을 읽습니다 — 스택(stack)이 무엇인지, 라우트(routes)가 어디에 있는지 파악합니다.
• app/main.py에 핸들러(handler)를 추가하며, 당신의 컨벤션(conventions)에 따라 입력을 검증합니다.
• 구조를 반영하여 tests/ 디렉토리에 pytest 테스트를 작성합니다.
• pytest, ruff, mypy를 실행합니다 — 당신이 그것이 기준(bar)이라고 알려주었기 때문입니다 — 그리고 실패하는 부분을 수정합니다.
• migrations/를 건드리지 않으며, main 브랜치에 커밋하지 않고 새로운 브랜치를 생성합니다.

이제 이 파일이 없는 상태에서 동일한 작업을 수행하는 모습을 상상해 보세요. 에이전트는 추측해야 합니다: 어떤 테스트 러너(test runner)를 써야 하지? 라우트는 어디에 있지? 린트(lint) 단계가 있나? 그래서 에이전트는 당신에게 질문을 던지거나, 잘못 추측하거나, 결국 당신이 되돌려야(revert) 할 생성된 파일을 수정하게 됩니다. AGENTS.md는 당신의 흐름을 방해하는 에이전트와, 그냥 작업을 완수(ship)하는 에이전트 사이의 차이점입니다.

이것이 바로 핵심적인 보상이며, 당신은 이 과정이 실시간으로 일어나는 것을 지켜볼 수 있습니다.

지속적으로 유지하기 (Keep it alive)

시작하기 전에 한 가지 습관을 들이세요: 이 파일을 코드처럼 취급하십시오. 테스트 명령어가 변경되거나, 디렉토리를 추가하거나, 에이전트에게 같은 말을 두 번 하고 있다는 사실을 깨닫는 즉시 — 그 자리에서 바로 AGENTS.md를 업데이트하세요. 오래된(stale) 파일은 파일이 없는 것보다 더 나쁩니다. 에이전트가 그 파일을 신뢰하기 때문입니다.

이것이 루프(loop)입니다

당신은 빈 파일로 시작하여 8개의 짧은 섹션을 추가했고, 에이전트가 일일이 가이드(hand-holding)를 받지 않고도 모든 섹션을 활용하여 정확하고 테스트가 완료된 변경 사항을 만들어내는 것을 지켜보았습니다. 한 번 작성해 두면, 당신의 리포지토리에 들어오는 모든 에이전트가 동일한 브리핑(briefing)을 받게 됩니다.

이것은 실습 중심의 구축 과정이었습니다. 각 섹션 뒤에 숨겨진 원칙 — 무엇이 포함되어야 하는지, 안티 패턴(anti-patterns)은 무엇인지, 왜 완전함보다 짧음이 더 나은지 — 에 대해서는 필드 가이드(field guide)를 참조하세요.