코딩 에이전트는 세션마다 빈 컨텍스트로 시작한다. 그래서 저장소에 대한 지식을 사람이 읽고 git으로 diff할 수 있는 평범한 텍스트 파일로 남겨 둔다. 한 줄로 줄이면 "규칙은 AGENTS.md로, 절차는 스킬로, 기억은 파일로"다.
규칙: AGENTS.md
- "에이전트를 위한 README"다. 저장소 루트에 두는 평범한 마크다운이고 필수 항목은 없다. 빌드·테스트 명령, 코드 스타일, 테스트 방법, 보안 주의점처럼 새 팀원에게 알려 줄 내용을 쓴다
- 모노레포라면 하위 프로젝트마다 둘 수 있고, 편집하는 파일에 가장 가까운 AGENTS.md가 이긴다. 사용자가 대화에서 직접 한 지시는 그보다 우선한다
- 지금은 리눅스 재단(Linux Foundation) 아래 Agentic AI Foundation이 관리하는 열린 형식이고 Codex, Copilot, Cursor 같은 여러 도구가 읽는다(2026 기준). Claude Code는 기본으로 CLAUDE.md를 읽고, CLAUDE.md가 없으면 AGENTS.md를 읽는다. 둘을 같이 쓰려면 CLAUDE.md에서
@AGENTS.md로 가져온다 - 짧고 구체적으로 쓴다: "모범 사례를 따르라"는 아무 방향도 주지 못한다. "소스를 고치면
npm run lint를 돌린다", "dist/는 고치지 않는다"처럼 쓴다. Claude Code 문서는 파일당 200줄 이하를 권하고, 길수록 컨텍스트를 먹고 지시를 덜 따른다고 말한다. Claude Code 팀도 저장소가 무엇인지는 짧게 쓰고, 토큰은 코드베이스의 함정(gotcha)에 쓰라고 권한다 - AAIF 블로그의 작은 실험(12줄짜리 AGENTS.md, 조건별 5회 실행)에서는 모호한 단순 과제에서 소요 시간이 27%, 크레딧이 24% 줄었고, 여러 파일을 고치는 과제에서는 중앙값 기준 9~10% 개선에 그쳤다. 크게 일반화할 숫자는 아니지만 짧은 파일도 효과가 있다는 정도는 보여 준다
절차: 스킬
스킬(Agent Skill)은 파일이 아니라 폴더다. SKILL.md 하나가 필수이고 scripts/, references/, assets/를 곁들일 수 있다.
---
name: pdf-processing
description: PDF에서 글과 표를 뽑고 양식을 채운다. PDF를 다룰 때 쓴다.
---
(여기부터 단계별 지침)- frontmatter의
name(소문자·숫자·하이픈, 64자 이하, 폴더 이름과 같아야 함)과description(1024자 이하)이 필수다. description에는 무엇을 하는지와 언제 쓰는지를 함께 적는다. 에이전트가 이걸 보고 스킬을 꺼낼지 정한다 - 점진적 공개(Progressive Disclosure): 시작할 때는 모든 스킬의 이름·설명(스킬당 100토큰 안팎)만 읽고, 스킬을 쓰기로 하면 본문(5000토큰 이하 권장)을, 나머지 파일은 필요할 때만 읽는다. 본문은 500줄 이하로 두고 긴 참고 자료는 따로 뺀다
- 결정론적으로 할 수 있는 부분은
scripts/의 스크립트로 분리한다
그래서 AGENTS.md가 길어지면 상황별 절차를 스킬로 밀어낸다. 항상 지켜야 하는 규칙만 AGENTS.md에 남는다.
기억: 파일
세션을 넘어 남길 배움(사용자의 교정, 반복되는 함정)도 작은 마크다운 파일로 둔다. Claude Code의 자동 메모리(Auto Memory)는 에이전트가 스스로 적는 노트로, 세션마다 인덱스 파일 MEMORY.md의 처음 200줄(또는 25KB)만 읽히고 주제별 파일은 필요할 때 읽힌다. 그러니 인덱스 항목은 한 줄로 짧게 두고 자세한 내용은 주제별 파일로 빼며, 낡은 항목은 합치거나 지운다. 상대 날짜("어제")는 나중에 뜻이 바뀌니 절대 날짜로 적는다. 새 모델이 나오면 지침이 아직 필요한지 점검하는 습관은 프론티어 팀의 습관에서 다룬다.
지시가 아니라 강제가 필요할 때
지침 파일은 맥락일 뿐 강제 설정이 아니다. 반드시 막아야 하는 행동은 훅이나 권한 설정으로, 반드시 통과해야 하는 기준은 테스트로 옮긴다 → 하네스 엔지니어링. 특정 모델의 약점을 메우려고 넣은 문장은 모델이 바뀌면 낡는다. 지침이 실제로 쓰이는 반복 구조는 에이전트 루프, 판정을 맡기는 구조는 생성과 평가 분리에서 다룬다.
출처: AGENTS.md · Agent Skills Specification · Claude Code 문서: How Claude remembers your project · Measuring AGENTS.md: What Five Runs Show That One Doesn't Andrea Griffiths, AAIF(2026-07-22) · The new rules of context engineering for Claude 5 generation models Thariq Shihipar(2026-07-24)