에이전트 지침: AGENTS.md·CLAUDE.md·SKILL.md

프로젝트 지침 파일

정의. 프로젝트 지침 파일은 코딩 에이전트가 그 프로젝트에서 작업할 때 읽도록 저장소에 두는 Markdown 파일이다. 특별한 문법은 없다. 에이전트는 이 텍스트를 작업의 맥락으로 받아들인다.

파일 이름. 도구마다 읽는 이름이 다르다. AGENTS.md는 여러 코딩 에이전트가 공통으로 읽도록 제안된 열린 형식으로, 스스로를 "에이전트를 위한 README"라고 소개한다. 필수 항목은 없고 보통의 Markdown이다. 일부 도구는 자기 이름이 붙은 파일을 읽는다. 예를 들어 Claude Code는 CLAUDE.md를 읽는다. 여러 도구를 함께 쓰는 프로젝트에서 같은 규칙을 파일마다 복사하면 언젠가 어긋난다. 이 책의 저장소는 규칙의 원천을 AGENTS.md 하나로 두고, CLAUDE.md에는 한 줄만 쓴다.

@AGENTS.md

@경로는 그 파일의 내용을 불러오라는 표기로, 이 저장소의 editorial/workflow.md도 "CLAUDE.md는 @AGENTS.md로 같은 규칙을 불러온다"고 설명한다. 이런 불러오기 문법이 있는지, 없으면 symbolic link나 짧은 안내 문장으로 대신해야 하는지는 도구마다 다르다.

전역·프로젝트·디렉터리 수준. 많은 도구가 지침을 여러 수준에 둘 수 있게 한다.

여러 수준의 지침이 충돌할 때의 규칙도 도구마다 다르다. AGENTS.md 형식이 제안하는 관례는 "고치는 파일에 가장 가까운 AGENTS.md가 우선하고, 사용자가 대화에서 명시한 지시가 모든 것에 우선한다"이다. 그래서 여러 하위 프로젝트가 있는 저장소(monorepo)에서는 루트에 공통 규칙을, 각 하위 디렉터리에 그 부분의 빌드·테스트 명령을 둔다.

확인 절차. 쓰는 도구가 어떤 파일을 읽는지는 다음 순서로 확인한다(도구와 버전에 따라 바뀌므로 이 책은 구체적인 목록을 싣지 않는다).

1. 도구의 공식 문서에서 지침 파일(memory, rules, instructions 등으로 부른다)의 이름, 위치, 여러 파일을 합치는 규칙을 찾는다.
2. 새 세션에서 에이전트에게 "지금 읽은 지침 파일과 그 핵심 규칙"을 요약하게 해, 의도한 파일이 실제로 읽혔는지 본다.
3. 지침에 일부러 확인용 규칙(예: "작업을 마칠 때 사용한 테스트 명령을 보고한다")을 넣고 그 규칙이 지켜지는지 본다.

지침은 권한이 아니다. 지침 파일에서 가장 흔한 오해다. 지침은 에이전트가 읽고 따르려고 하는 텍스트이지, 행동을 막는 장치가 아니다. 대부분의 경우 지켜지지만, 긴 작업 중에 다른 맥락에 밀리거나, 규칙을 다르게 해석하거나, 외부 문서에 들어 있던 지시에 휘둘릴 수 있다(4.5장). 그래서 "절대 일어나면 안 되는 일"은 층을 나눠 막는다.

이 저장소의 .claude/settings.json은 python3 scripts/book.py check·outline·stats 같은 저장소 자체의 검사·생성 명령만 승인 없이 실행하도록 허용한다. 지침이 "변경 후 check를 실행한다"고 말하고, 권한 설정이 그 명령을 마찰 없이 실행하게 하고, check 스크립트가 규칙 위반을 잡는다. 세 층이 같은 규칙을 다른 방식으로 받친다.

무엇을 쓰는가

원칙. 지침에는 에이전트가 매번 필요로 하지만 코드만 읽어서는 알기 어려운 것을 쓴다. 반대로 코드에서 바로 읽히는 것(함수가 무엇을 하는지), 가끔만 필요한 긴 설명(이론 배경), 그리고 비밀값은 쓰지 않는다.

프로젝트 구조. 디렉터리마다 무엇이 있는지 한두 줄로. 특히 "어디에 무엇을 두는가"의 규칙. 이 책의 AGENTS.md는 "이 저장소는 코드 프로젝트가 아니라 책이다"로 시작해, 에이전트가 저장소를 소프트웨어로 오해하지 않게 한다. 그다음 먼저 읽을 문서 네 개를 순서대로 가리킨다. 긴 규칙을 지침에 다 쓰지 않고, 원천 문서를 가리키는 방식이다.

설치·실행·테스트 명령. 지침에서 가장 쓸모 있는 부분이다. 그대로 복사해 실행할 수 있는 정확한 명령을 쓴다. "테스트를 돌린다"가 아니라 python -m pytest -q tests. 그리고 작업이 끝났다는 기준이 되는 명령을 명시한다. 이 저장소의 지침은 "변경 후 python3 scripts/book.py check를 실행하고 통과시킨다"고 쓴다. 이 한 줄이 있으면 에이전트는 작업을 마치기 전에 스스로 검사하고, 사람은 보고에서 그 결과를 확인할 수 있다.

금지사항. 하지 말아야 할 일을 구체적으로. "조심한다"가 아니라 "OUTLINE.md는 직접 수정하지 않는다(생성 파일이다)", "장 id를 바꾸지 않는다(사용자 진도 기록의 키다)". 이유를 함께 쓰면 에이전트가 규칙이 적용되는 범위를 더 정확히 판단한다. 비슷한 상황에서 규칙의 취지를 따를 수 있기 때문이다.

검증 기준. 작업 결과를 어떻게 확인하는가. 이 저장소에서는 "실습 코드는 실제로 실행해 본 결과만 본문에 쓴다", "존재를 직접 확인하지 않은 논문·API·수치를 쓰지 않는다"가 그렇다. 연구 프로젝트라면 "새 실험은 seed 3개로 돌리고 평균과 표준편차를 보고한다", "test split의 결과는 최종 보고 전에는 보지 않는다" 같은 규칙이 여기 들어간다.

데이터 취급 규칙. 연구 프로젝트에서 특히 중요하다. 원본 데이터는 읽기 전용, 개인정보·공개 전 데이터는 외부 서비스로 보내지 않음, 데이터의 위치와 접근 방법, 용량이 큰 파일을 열 때의 주의.

길이. 지침은 짧을수록 잘 지켜진다. 규칙이 백 개면 어느 것이 중요한지 에이전트도 사람도 모른다. 이 책의 AGENTS.md는 39줄이다. 길어지면 다음을 시도한다.

• 기계적으로 확인할 수 있는 규칙은 지침에서 빼고 검사 스크립트로 옮긴다. 이 저장소의 frontmatter 형식, 고정 절 제목, 선수 지식의 레이어 규칙은 book.py check가 검사하므로 지침에는 "check를 통과시킨다" 한 줄이면 된다.
• 특정 작업에만 필요한 절차는 skill로 옮긴다(다음 절).
• 하위 디렉터리에만 해당하는 규칙은 그 디렉터리의 지침 파일로 옮긴다.

Skill

왜 필요한가. 지침 파일은 항상 맥락에 들어간다. 그래서 가끔 하는 작업의 상세 절차까지 넣으면 지침이 길어지고, 핵심 규칙이 묻힌다. 반복 작업의 절차는 따로 묶어 두고, 그 작업을 할 때만 꺼내 쓰는 편이 낫다. 이것이 skill이다.

정의. skill은 반복 작업 하나의 절차를 담은 폴더다. 형식은 Agent Skills 명세로 공개되어 있다. 폴더 안의 SKILL.md는 YAML frontmatter와 본문으로 이루어진다. frontmatter의 필수 항목은 두 개다.

• name — skill의 이름. 소문자·숫자·하이픈만 쓰고, 폴더 이름과 같아야 한다.
• description — 이 skill이 무엇을 하는지와 언제 쓰는지

본문에는 절차, 확인할 것, 예시를 쓴다. 이 책 저장소의 skill 하나를 보면 구조가 보인다.

---
name: add-quiz
description: 장의 학습 목표에 맞는 개념 퀴즈 문항을 quiz.toml에 추가한다. 사용자가 퀴즈·객관식 문제·문제집 작성을 요청할 때 사용한다.
---

# 퀴즈 문항 추가

## 준비
1. 장 파일의 `## 학습 목표`를 읽고 번호를 매긴다(1부터).
...
## 검증
- **모든 정답을 직접 풀어서 확인한다.** 계산 문항은 코드로 확인한다.
...

description과 트리거. 명세는 skill을 단계적으로(progressive disclosure) 읽는 구조를 설명한다. 에이전트는 시작할 때 모든 skill의 name과 description만 맥락에 두고, 지금 작업에 어떤 skill이 필요하다고 판단하면 그때 그 SKILL.md 본문 전체를 읽고, 본문이 가리키는 보조 파일은 필요할 때만 연다. 그래서 description은 에이전트가 "이 요청에 이 skill을 써야 하는가"를 판단하는 유일한 근거다. 무엇을 하는지만 쓰지 말고 어떤 요청·상황에서 쓰는지를 구체적으로 쓴다. 사용자가 쓸 법한 표현("퀴즈", "객관식 문제", "문제집")을 넣는 것도 도움이 된다. 이 저장소의 skill은 사용자가 이름으로 직접 부를 수도 있다(/write-chapter처럼). skill의 위치(이 저장소는 .claude/skills/<이름>/SKILL.md)와 호출 방법은 도구마다 다르므로 도구 문서에서 확인한다.

보조 스크립트. skill 폴더에는 SKILL.md 외에 스크립트, 템플릿, 참고 문서를 함께 둘 수 있다. 명세는 이를 scripts/, references/, assets/ 폴더로 정리하기를 권하고, 본문은 짧게(500줄 이내) 유지하고 긴 참고 자료는 별도 파일로 옮기라고 권한다. 본문에서 "형식 검사는 scripts/validate.py를 실행한다"처럼 가리키면, 에이전트는 필요할 때 그 파일을 읽거나 실행한다. 정해진 계산이나 형식 변환은 자연어 절차보다 스크립트가 훨씬 안정적이다. 매번 같은 결과를 내고, 맥락을 차지하지 않기 때문이다.

좋은 skill의 조건.

• 한 가지 일을 한다. "퀴즈 추가"와 "장 리뷰"는 다른 skill이다. 이 저장소의 세 skill(write-chapter, review-chapter, add-quiz)이 그렇게 나뉘어 있다.
• 끝나는 조건이 있다. 어떤 검사를 통과하면 끝인지, 무엇을 보고하는지를 쓴다. write-chapter는 "status를 draft로 바꾼다, check를 실행한다, 쓴 절·실습·확인 필요 목록을 보고한다"로 끝난다.
• 하지 말아야 할 일을 쓴다. review-chapter는 description부터 "파일은 고치지 않는다"고 쓴다. 리뷰와 수정을 섞지 않기 위해서다.
• 사람에게 넘길 지점을 쓴다. 판단이 필요한 곳(단위가 없으면 묻는다, 허용 오차가 애매하면 확인받는다)에서 멈추게 한다.

지침의 유지보수

지침도 코드다. 지침은 저장소에 commit하고, 바꿀 때는 PR로 리뷰를 받는다. 지침 한 줄이 이후 모든 에이전트 작업의 방식을 바꾸기 때문이다. 코드와 지침을 함께 바꾸는 변경(명령 이름 변경, 디렉터리 이동)이라면 같은 PR에서 고친다. 이 저장소의 AGENTS.md도 "목차 구조를 바꿨다면 python3 scripts/book.py outline으로 OUTLINE.md를 재생성한다"처럼 코드 변경과 함께 해야 할 일을 적어 둔다.

지침과 실제 코드의 불일치. 가장 흔한 고장은 지침에 적힌 명령이 더는 동작하지 않는 것이다. 스크립트 이름이 바뀌었거나, 옵션이 없어졌거나, 디렉터리가 옮겨졌다. 에이전트는 실패한 명령을 보고 다른 방법을 추측하거나, 실패를 무시하고 진행하거나, 옛 스크립트를 다시 만든다. 이 불일치는 사람이 읽어서는 잘 보이지 않으므로 기계적으로 검사한다. 이 장의 실습 폴더에 있는 check_instructions.py는 다음을 한다.

• AGENTS.md와 각 SKILL.md의 ```bash 블록에 적힌 명령을 프로젝트 디렉터리에서 실제로 실행해 실패를 보고한다.
• AGENTS.md가 가리키는 상대 경로가 실제로 있는지 본다.
• SKILL.md frontmatter의 name 형식, 폴더 이름과의 일치, description의 길이를 검사한다.

이런 검사를 CI에 넣으면 지침이 코드와 함께 낡는 것을 막을 수 있다.

오래된 지침 정리. 지침은 늘어나기만 하는 경향이 있다. 사고가 한 번 날 때마다 규칙이 하나씩 더해진다. 주기적으로(예: 큰 작업 단위가 끝날 때) 다음을 확인한다.

• 이 규칙이 아직 필요한가? 원인이 된 코드가 없어졌거나 검사 스크립트가 대신하게 되었으면 지운다.
• 두 규칙이 서로 모순되지 않는가?
• 이 규칙이 지침 파일에 있어야 하는가, skill이나 하위 디렉터리 지침으로 옮길 수 있는가?

에이전트의 실수에서 배운다. 에이전트가 같은 실수를 두 번 하면 지침이 부족하다는 신호다. 다만 실수마다 규칙을 하나씩 더하기 전에, 그 실수를 검사로 막을 수 있는지 먼저 본다. 검사는 지침보다 확실하다.

참고 문헌

• AGENTS.md. https://agents.md — 에이전트 지침 파일의 열린 형식과 우선순위 관례
• Agent Skills Specification. https://agentskills.io/specification — SKILL.md의 frontmatter 규칙(name, description), 폴더 구성, 단계적 로딩
• anthropics/skills 저장소. https://github.com/anthropics/skills — skill 예시와 템플릿