/init로 AGENTS.md를 자동 생성하면 시작은 편합니다. 문제는 그 다음입니다. README와 코드에서 이미 확인 가능한 정보까지 길게 붙기 시작하면, 모델은 매번 불필요한 문장을 함께 읽게 되고 비용과 집중력이 같이 떨어집니다.
핵심은 “문서를 많이 쓰는 것”이 아니라 “상시로 붙어야 할 문장만 남기는 것”입니다. 이 글은 공개된 논의와 공식 문서를 근거로, AGENTS.md를 짧고 단단하게 운영하는 방법을 실무형으로 정리했습니다.
안내: 이 문서는 생성형 AI를 활용해 초안을 작성했고, 공개 자료를 교차 확인해 실무형으로 정리했습니다.
이 글의 근거 자료
- 현장 논의(관측):
/init자동 생성 문서가 중복 컨텍스트를 늘려 비용을 키운 사례 공유 - OpenAI Prompt Engineering: 지시문은 명확·간결하게 유지할수록 유리
- OpenAI Eval Skills: 품질은 문서 길이보다 평가 루프가 좌우
- Claude Code Skills / Anthropic Engineering: 작업별 스킬 분리 운영 원칙
핵심 요약
- 자동 생성 자체가 문제라기보다, 중복된 상시 컨텍스트가 문제입니다.
- AGENTS.md는 소개서가 아니라 운영 제약 문서에 가깝게 유지해야 합니다.
- 실패를 줄이려면 문서를 길게 쓰는 것보다 테스트/평가/작업별 스킬 라우팅을 먼저 붙이는 편이 안정적입니다.
flowchart LR A[/init 자동 생성] --> B{코드로 이미 알 수 있는 정보 중복?} B -->|Yes| C[상시 컨텍스트 비대화] C --> D[비용 증가 + 집중력 저하] B -->|No| E[핵심 규칙만 유지] E --> F[작업별 스킬 라우팅] F --> G[비용 안정 + 품질 개선]
🧠 칠판 치트시트
- AGENTS.md는 “전체 지도”가 아니라 “사고 방지 표지판”이다
- 코드로 확인 가능한 설명은 과감히 뺀다
- 상시 문서에는 금지/필수/예외/복구만 남긴다
- 반복 실패는 문서가 아니라 테스트/가드레일로 막는다
- 작업별 규칙은 스킬 문서로 분리해 필요할 때만 불러온다
왜 /init 자동생성이 비용 함정이 되기 쉬운가
첫째, 상시 컨텍스트는 매 요청마다 과금과 추론 부담을 만듭니다. 길이가 2배가 되면, 단순 질의에서도 모델이 읽어야 할 양이 함께 늘어납니다. OpenAI 문서가 반복해서 강조하는 “명확하고 간결한 지시” 원칙과도 맞닿아 있습니다.
둘째, 정보가 많아질수록 오히려 우선순위가 흐려집니다. 정말 중요한 금지 규칙 3줄이, 덜 중요한 설명 30줄에 묻히는 순간 운영 사고가 늘어납니다.
셋째, 반복 실패의 원인을 문서 길이에서 찾기 시작하면 개선이 늦어집니다. 같은 실수가 재발할 때는 대개 “읽었는가”보다 “강제되는가”가 더 중요합니다. 즉, 테스트·린트·평가 루프가 먼저여야 합니다.
현장에서 자주 보는 패턴 3가지
패턴 A) 문서는 두꺼운데 팀은 계속 같은 실수를 반복
증상은 단순합니다. “지침은 분명히 있었는데 놓쳤다”가 반복됩니다. 이 경우 문서를 더 늘려도 개선이 거의 없습니다. 읽기 의존 구조를 실행 강제 구조로 바꿔야 합니다.
패턴 B) 간단한 작업에도 무거운 지시가 매번 붙음
문서 수정 하나에도 빌드/배포/아키텍처 규칙이 통째로 붙으면, 비용도 늘고 응답도 느려집니다. 작업 유형별 분리가 없을 때 흔히 생깁니다.
패턴 C) 팀원이 바뀌면 품질이 다시 흔들림
문서가 장황할수록 사람마다 중요 포인트를 다르게 읽습니다. 반대로 핵심 규칙이 짧고 분명하면 온보딩 품질 편차가 줄어듭니다.
미니 사례 3가지
사례 1) 스타트업 앱팀: AGENTS 180줄 → 28줄
앱팀은 /init 이후 생성된 설명을 계속 붙이며 운영하다가, 소규모 작업에도 비용이 커지고 응답 품질 편차가 생겼습니다. 팀은 과감히 정리했습니다.
- 상시 문서에는 “필수 도구, 금지 작업, 테스트 게이트, 복구 기본값”만 남김
- 기술 소개·폴더 설명은 README로 이동
- 작업별 세부 규칙은 별도 스킬 문서로 분리
결과적으로 문서 길이보다 “규칙 선명도”가 올라가서, 리뷰 시간이 줄고 재작업 비율도 낮아졌습니다.
사례 2) 백오피스 운영팀: 가이드 확장보다 테스트 자동화 우선
운영팀은 에이전트가 자주 틀리는 포인트(필수 필드 누락, 날짜 포맷 오류)를 매번 문장으로 경고했지만 반복 실패가 줄지 않았습니다.
- 경고 문장 추가를 멈추고, pre-check 스크립트로 형식 검증 자동화
- 실패 시 즉시 재생성하도록 파이프라인 고정
- AGENTS에는 “무엇을 실행해야 하는지”만 짧게 명시
핵심은 “읽어야 아는 규칙”을 “실행하면 강제되는 규칙”으로 바꾼 것입니다.
사례 3) 콘텐츠 팀: 작업별 스킬 라우팅으로 비용 안정화
콘텐츠 팀은 글쓰기·이미지·배포 작업을 하나의 상시 지시문으로 처리했습니다. 결과는 단순 작업에도 과한 컨텍스트였습니다.
- 글쓰기 스킬, 이미지 스킬, 배포 스킬을 분리
- 요청 분류 후 필요한 스킬만 로드
- 공통 AGENTS에는 보안/금지/승인 정책만 유지
이후 단순 편집 작업의 응답 속도와 비용이 모두 안정됐습니다.
AGENTS.md를 짧고 강하게 만드는 구조
실무에서는 아래 4덩어리만 남겨도 충분한 경우가 많습니다.
- 절대 금지/보안 경계
- 필수 실행 게이트(테스트/검증)
- 도구·명령 사용 원칙
- 실패 시 기본 복구 순서
예시 스켈레톤:
## Must not
- 민감정보 외부 전송 금지
- 승인 없는 파괴적 작업 금지
## Must run
- 변경 전/후 테스트 필수
- 실패 시 로그 첨부 후 재시도
## Tool policy
- 기본 도구와 허용 범위
## Recovery
- 장애 시 롤백/복구 순서작업별 상세 규칙은 스킬 문서로 분리해 “필요할 때만” 로드하는 편이 운영 효율이 좋습니다.
- 참고: https://code.claude.com/docs/en/skills
- 참고: https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills
30분 리팩터링 루틴
- 10분: AGENTS에서 코드로 확인 가능한 문장 제거
- 10분: 반복 오류 1개를 테스트/체크 스크립트로 강제
- 10분: 작업별 스킬 분리 + 라우팅 문장 추가
이 루틴을 한 번만 돌려도, “문서 길이는 긴데 체감 품질은 낮은” 상태에서 빠르게 벗어날 수 있습니다.
점검 메모
- 상시 문서에서 중복 설명을 걷어냈는가
- 반복 실패 1개 이상을 자동 검증으로 막았는가
- 작업별 규칙이 스킬/레퍼런스로 분리됐는가
- 비용·성공률·완료시간의 전후 비교를 기록했는가