Molayo

© 2026 Molayo

Qiita헤드라인2026. 06. 27. 16:57

AGENTS.md를 길게 작성한다고 해서 AI agent가 반드시 똑똑해지는 것은 아니다

요약

AI 코딩 에이전트를 위한 AGENTS.md 작성 시, 과도한 정보 입력이 오히려 에이전트의 판단력을 흐리는 '컨텍스트 팽창'을 유발할 수 있음을 경고합니다. 에이전트용 지시 사항은 정책 파일로서 핵심적인 경계(Boundaries) 위주로 압축하여 작성해야 합니다.

핵심 포인트

  • AGENTS.md에 너무 많은 정보를 담으면 에이전트의 판단 재료가 흐려짐
  • 컨텍스트 팽창(Context Bloat)을 방지하기 위해 정보를 압축해야 함
  • 기계가 판단 가능한 규칙(포맷팅, 타입 등)은 도구에 맡기고 경계 위주로 작성
  • README는 인간을 위해, AGENTS.md는 에이전트의 실행 효율을 위해 분리

AGENTS.md

또는 CLAUDE.md

를 두면, AI coding agent가 갑자기 repo(저장소)를 이해해 주는 듯한 느낌이 듭니다.

처음에는 상당히 편리합니다. pnpm을 사용한다, src/generated는 건드리지 않는다, UI를 변경하면 screenshot(스크린샷)을 확인한다, 와 같은 규칙을 매번 prompt(프롬프트)에 쓸 필요가 없어집니다.

하지만, 여기서 우쭐해서 모든 것을 쓰기 시작하면, 점점 효과가 떨어집니다.

lint(린트) 선호도. deploy(배포) 절차. 과거의 사고. 명명 규칙. 리뷰 관점. 프로덕트의 배경. 오래된 migration(마이그레이션) 주의사항. 이 모든 것을 한 장에 몰아넣으면, agent는 매번 그것을 읽어야 합니다. 인간도 읽지 않습니다. 읽히지 않는 instruction(지시 사항)은 대개 망가집니다.

최근에는 AGENTS.md를 「긴 prompt」가 아니라, repo의 policy file(정책 파일)로 보는 것이 좋다고 생각합니다. 쓰는 양을 늘리기보다, agent가 망설일 여지를 줄이는 것. 그쪽으로 맞추는 것이 실용적이었습니다.

README는 인간을 위한 것입니다.

배경, 설계 사상, 사용 중인 library(라이브러리)의 이유, 로컬 개발 절차, 운영의 맥락. 이런 것들을 읽으며 개발자는 repo에 들어옵니다.

AGENTS.md는 다릅니다. agent가 매번 읽을 가능성이 있으므로, 항상 읽을 가치가 있는 정보로만 압축하고 싶습니다.

저라면 우선 이 정도로 하겠습니다.

# AGENTS.md
## Boundaries
- Do not edit files under `src/generated/`.
...

이것만으로도 긴 편입니다.

여기에 「이 프로덕트가 무엇을 목표로 하는가」를 20줄 쓰고 싶어지는 마음은 이해합니다. 하지만 대부분의 edit task(수정 작업)에서는 방해가 됩니다. 필요하다면 docs(문서)에 둡니다. 태스크 고유의 내용이라면 issue(이슈)나 brief(브리프)에 씁니다. 항상 읽어야 하는 instruction에 넣지 않습니다.

AGENTS.md smells(냄새/문제점)를 다룬 최근 연구에서는, repo-level instruction(저장소 수준 지시 사항)에서 일어나기 쉬운 문제로서 Context Bloat(컨텍스트 팽창), Lint Leakage(린트 누출), Skill Leakage(기술 누출)와 같은 분류가 나옵니다.

이름은 약간 연구 같지만, 현장에서 보는 증상은 매우 일반적입니다.

예를 들어 CSS의 한 줄 수정을 부탁했을 뿐인데, agent가 deploy 절차, DB 명명 규칙, API 설계 사상까지 읽고 있습니다.

이것은 똑똑해진다기보다, 판단 재료가 흐려지는 것입니다. agent는 「이번 작업과 관계있는 정보」와 「언젠가 도움이 될 정보」를 인간만큼 대충 버리지 못합니다.

특히 frontend(프론트엔드) repo라면 UI, API client, test, design token, build, deploy가 하나의 instruction file에 뒤섞이기 쉽습니다. 편리해 보이지만, 매번 전부 읽을 필요는 없습니다.

이런 instruction을 자주 봅니다.

- Use consistent formatting.
- Prefer readable code.
- Avoid unnecessary complexity.
...

마음은 이해합니다. 하지만 이것은 agent에게도 인간에게도 약합니다.

format(포맷)은 formatter(포맷터)에게 맡깁니다. 타입은 TypeScript에 맡깁니다. test로 걸러낼 수 있는 것은 test에 맡깁니다. 문장으로 가져가야 할 것은, 기계가 판단하기 어려운 경계뿐입니다.

- Do not introduce a new state management library without explicit approval.
- Do not add browser-only APIs to files imported by SSR routes.
- Keep public route changes backward compatible unless the task says otherwise.

이 정도라면 판단에 효과적입니다.

이미지 생성 기사를 쓸 때만 필요한 SEO 규칙. 특정 platform(플랫폼)에 게시할 때만 필요한 frontmatter. 어떤 customer(고객)를 위한 일시적인 제약.

이런 것들을 전부 AGENTS.md에 넣으면, 관계없는 task에서도 매번 섞여 들어옵니다.

저라면 여기는 분리하겠습니다.

AGENTS.md
레포지토리(repo) 전체의 경계와 금지 사항
docs/ai-writing.md
...

agent에게 무엇이든 기억시키기보다, 필요한 시점에 필요한 파일(file)을 읽게 하는 편이 더 안정적입니다.

AGENTS.md에 넣는 내용은 상당히 압축합니다.

AGENTS.md
- 건드리면 안 되는 경로(path)
- 파괴적인 명령어(command) 금지
...

포인트는 문장으로 해결하려 애쓰지 않는 것입니다.

AGENTS.md에 "반드시 품질 높은 코드(code)를 작성해 주세요"라고 쓰는 것보다, pnpm test가 실패하게 만드는 것이 더 강력합니다. 기존 스타일(style)에 맞춰 주세요라고 쓰는 것보다, 포매터(formatter)와 린트 규칙(lint rule)에 맞추는 것이 더 빠릅니다.

agent는 문장을 읽을 수 있습니다. 하지만 실행 가능한 체크(check)가 훨씬 더 신뢰할 수 있습니다.

나쁜 예시부터 보겠습니다.

## Coding style
This project values readable, maintainable, high-quality code. Please make sure
to follow the existing frontend architecture, keep components small, avoid
...

말하는 내용은 맞습니다. 하지만 무엇을 해야 완료인지가 모호합니다.

저라면 이렇게 하겠습니다.

## Verification
- TypeScript / Vue changes: run `pnpm lint`.
- Shared logic under `app/utils/`: run `pnpm test`.
...

아직 완벽하지는 않지만, agent가 움직이기 쉽습니다.

"깔끔하게 해줘"가 아니라, "이 명령어(command)를 통과시켜라", "이 경로(route)를 확인해라", "이 종류의 변경은 하지 마라"라고 쓰는 것입니다. 판단이 아니라 절차에 가깝게 작성합니다.

AGENTS.md가 길어지기 시작하면, 다음 사항들을 한 번 점검하여 내용을 크게 줄일 수 있습니다.

  • 이 줄은 모든 태스크(task)에서 필요한가
  • 명령어로 바꿀 수 있는 것을 문장으로 설명하고 있지는 않은가
  • 오래된 배포(deploy) 절차나 오래된 도구(tool) 이름이 남아 있지 않은가
  • 이슈(issue)나 PR 템플릿(template)에 두는 것이 더 자연스럽지 않은가
  • CI에서 걸러내는 것이 더 빠르지 않은가
  • agent가 읽는 것보다 문서(docs) 링크만으로 충분하지 않은가
  • 그 제약 사항을 지금도 실제로 지키고 있는가

특히 마지막 항목이 중요합니다.

사람이 지키지 않는 규칙(rule)을 agent에게만 지키게 하려고 하면, 대개 이상한 디프(diff)가 발생합니다. 레포지토리(repo)의 실태와 지침(instruction)이 어긋나 있다면, 먼저 지침을 줄이거나 실태에 맞게 수정하는 것이 좋습니다.

항상 읽어야 하는 AGENTS.md는 가볍게 유지하고, 대신 태스크(task)별 브리프(brief)를 상세하게 작성하는 것이 매우 효과적입니다.

예를 들어 UI 수정이라면, 프롬프트(prompt)나 이슈(issue)에 다음과 같이 작성합니다.

## Acceptance criteria
- `/settings/profile`의 아바타 업로드 UI만 변경할 것
- API 컨트랙트(contract)는 변경하지 말 것
...

이것은 AGENTS.md가 아닙니다. 이번에만 적용되는 조건입니다.

레포지토리(repo) 전체의 지침(instruction)에 넣으면 노이즈가 되지만, 이 태스크(task)에서는 강력한 컨텍스트(context)가 됩니다. 연구에서도 넓은 레포지토리 컨텍스트(repo context)가 항상 성공률을 높이는 것이 아니라, 좁은 태스크 컨텍스트(task context)가 효과적인 경우가 더 많습니다.

agent에게 읽히는 정보는 "많을수록 좋은 것"이 아니라 "현재의 변경 사항과 가까울수록 좋은 것"입니다.

그렇다고 짧으면 무조건 이긴다는 뜻도 아닙니다.

아무것도 쓰지 않으면, agent는 레포지토리(repo)의 지뢰를 밟습니다. 생성된 파일(generated file)을 수정하거나, 멋대로 마이그레이션(migration)을 건드리거나, 글로벌 CSS를 수정하거나, 테스트(test)를 실행하지 않고 끝내버립니다.

따라서 짧게 만드는 목적은 "정보를 줄이는 것"이 아니라, "매번 읽어야 할 정보만 남기는 것"입니다.

제 느낌으로는, 좋은 AGENTS.md는 체크리스트(checklist)에 가깝습니다. 읽고 감동할 필요는 없습니다. agent가 불필요한 행동을 하지 않게 하고, 리뷰어(reviewer)가 "이 레포지토리(repo)의 작업 경계는 여기구나"라고 바로 알 수 있으면 충분합니다.

AGENTS.md를 잘 가꾸어 나가는 것은 중요합니다.

하지만, 에이전트(agent)에게 모든 것을 가르치는 장소는 아닙니다. 레포지토리(repo)의 경계, 금지된 작업, 검증 커맨드(command), 변경해도 되는 위치. 그곳에 집중하는 것이 매 작업 시 더 효과적입니다.

배경 설명은 docs로 넘기세요. 스타일(style)은 린트(lint)와 포매터(formatter)로 넘기세요. 강제하고 싶은 게이트(gate)는 CI로 넘기세요. 이번에만 해당하는 조건은 이슈(issue)나 브리프(brief)에 작성하세요.

긴 인스트럭션(instruction)보다, 짧은 경계와 실행 가능한 확인이 더 중요합니다.

AI 에이전트(agent)를 레포지토리(repo)에 도입한다면, 우선 AGENTS.md에 내용을 추가하기 전에 "이것을 정말 매번 읽게 하고 싶은가?"를 한 번 의심해 보는 것이 좋습니다.

AGENTS.md 인스트럭션 파일(instruction file)의 냄새(smell) 분류: https://arxiv.org/abs/2606.15828 - 레포지토리 레벨 컨텍스트 파일(repo-level context file)의 효과와 비용(cost)에 관한 평가: https://arxiv.org/abs/2602.11988

AI 자동 생성 콘텐츠

본 콘텐츠는 Qiita AI의 원문을 AI가 자동으로 요약·번역·분석한 것입니다. 원 저작권은 원저작자에게 있으며, 정확한 내용은 반드시 원문을 확인해 주세요.

원문 바로가기
0

댓글

0