코드 에이전트(code agents)가 실패하는 이유는 단지 모델 때문만이 아닙니다. 그들은 당신의 레포지토리(repo)에서 어떻게 작업하는지 모르기 때문에 실패합니다. 프로젝트 지침은 시스템의 일부입니다.

훌륭한 AGENTS.md 또는 CLAUDE.md는 모델에게 프로그래밍을 가르치려 하지 않습니다. 대신 해당 프로젝트에서 어떻게 작업하는지를 가르칩니다: 명령(commands), 제한 사항, 컨벤션(conventions), 아키텍처(architecture), 테스트(tests), 커밋 스타일(commit style) 및 허가 없이 건드려서는 안 되는 영역들입니다.

아이디어

이러한 컨텍스트는 매우 흔한 유형의 오류를 줄여줍니다: 에이전트가 추상적으로는 합리적이지만 당신의 레포지토리에는 맞지 않는 행동을 하는 경우입니다. 잘못된 테스트를 실행하거나, 생성기(generator)를 무시하거나, 생성된 코드를 편집하거나, 팀이 사용하지 않는 컨벤션을 적용하는 식입니다.

포함해야 할 내용

• 실제로 사용되는 설치, 테스트 및 린트(lint) 명령.
• 레포지토리 구조 및 기본적인 소유권(ownership).
• 새로운 추상화(abstractions)를 만들기 전에 복사해야 할 패턴.
• 생성된 파일 또는 수동으로 편집해서는 안 되는 영역.
• 마이그레이션(migrations), 시드(seeds), 픽스처(fixtures) 및 민감한 데이터에 대한 정책.
• Git 규칙: 브랜치(branches), 커밋(commits), PR 및 메시지.
• 작업을 완료된 것으로 간주하기 전의 검증 기준.

포함하지 말아야 할 내용

전체 문서를 넣지 마세요. 너무 긴 지침 파일은 노이즈(noise)가 됩니다. 비밀(secrets), 토큰(tokens), 개인 정보 또는 빠르게 만료되는 일시적인 결정 사항도 포함하지 마세요.

프로젝트 메모리는 안정적이어야 합니다. 만약 어떤 규칙이 오늘만 적용되는 것이라면, 티켓(ticket)이나 프롬프트(prompt)에 넣는 것이 더 낫습니다. 항상 적용되는 것이라면 컨텍스트 파일에 머물 가치가 있습니다.

우선순위 및 범위

어려운 문제는 지침을 작성하는 것이 아니라, 여러 개가 있을 때 어떤 것이 적용되는지 아는 것입니다. Codex, Claude Code 및 기타 에이전트들은 글로벌(global), 프로젝트(project) 또는 하위 디렉토리(subdirectory) 지침을 읽을 수 있습니다. 이는 정밀함을 가능하게 하지만, 충돌을 일으킬 수도 있습니다.

실용적인 규칙은 명확한 계층 구조를 갖는 것입니다: 개인적인 선호도는 전역(global) 설정으로, 프로젝트 규범은 저장소 루트(repo root)에, 로컬 예외 사항은 하위 디렉토리(subdirectory)에 배치합니다. 만약 두 파일이 서로 충돌한다면, 에이전트는 즉흥적으로 판단할 수 있습니다. 이를 방지하려면 철학적인 내용이 아닌 구체적인 지침을 작성하세요.

유용한 섹션 예시

Tests: 백엔드 변경 시에는 npm test -- --runInBand를 사용하고, 컴포넌트가 변경될 때만 npm run test:ui를 사용하세요. 체크아웃(checkout), 로그인(login) 또는 권한(permissions) 관련 변경이 아닌 한 전체 E2E 테스트 스위트를 실행하지 마세요.

이러한 유형의 지침은 적절한 테스트를 실행하라는 말보다 훨씬 낫습니다. 왜냐하면 모호한 결정을 줄여주기 때문입니다. 에이전트는 당신의 팀에서 '적절한' 것이 무엇을 의미하는지 추측할 필요가 없습니다.

유지보수

워크플로우(workflow)가 변경될 때마다 지침을 검토하세요. 만약 Jest에서 Vitest로 마이그레이션했는데 파일에 여전히 Jest라고 적혀 있다면, 에이전트는 거짓 정보를 따르게 됩니다. 아키텍처(architecture)를 변경하고 소유권(ownership)을 업데이트하지 않으면, 에이전트는 잘못된 곳을 건드리기 시작할 것입니다.

점검해야 할 사항

반복적인 실패가 발생한 후에는 지침을 감사(audit)하는 것도 좋습니다. 에이전트가 동일한 실수를 두 번 반복할 때, 항상 더 긴 프롬프트(prompt)가 필요한 것은 아닙니다. 때로는 짧고 검증 가능한 프로젝트 규칙이 부족한 것일 수 있습니다.

결론

지침 파일은 인간-에이전트 협업을 위한 인프라(infrastructure)입니다. 이것이 테스트나 리뷰(revision)를 대체하지는 않지만, 에이전트가 각 작업을 올바른 지도와 함께 시작할 수 있도록 해줍니다.

좋은 파일은 '주의를 기울여라'라고 말하지 않습니다. 해당 저장소에서 작업이 어떻게 구축되고, 테스트되고, 리뷰되고, 제한되는지를 정확하게 말해줍니다.

조사와 범위가 제한된 작업은 병렬화(parallelize)하세요. 기술적 판단이나 최종 통합(integration)은 병렬화하지 마세요.

출처 및 참조

출처 및 참조

• OpenAI Codex: AGENTS.md
• Claude Code memory
• Claude Help: CLAUDE.md and better prompts
• Configuring Agentic AI Coding Tools

이것은 크로스 포스팅된 버전입니다. 원래는 devaisemanal.com에 게시되었습니다.

도움이 되셨나요? DevAI Semanal을 무료로 구독하세요(https://devaisemanal.com/?utm_source=devto&utm_medium=crosspost&utm_campaign=spanish_digest#/portal/signup) — 매주 화요일, 스페인어 개발자를 위한 AI 도구와 잡음 없는 정보.