코덱스 툴 사용법 04: AGENTS.md로 반복 지침 고정하기 | DAKER 커뮤니티

코덱스 툴 사용법 04: AGENTS.md로 반복 지침 고정하기

코덱스를 하루에 여러 번 쓰다 보면 같은 말을 계속 반복하게 된다. "테스트 먼저 봐줘", "대규모 리팩터링은 하지 마", "완료 보고에는 실행한 명령을 적어줘" 같은 지시다. 이 반복 지침은 프롬프트에 매번 붙이는 것보다 AGENTS.md에 고정하는 편이 낫다.

OpenAI 공식 문서 기준으로 AGENTS.md는 에이전트를 위한 open-format README처럼 자동으로 컨텍스트에 들어가는 파일이다. 전역, 저장소, 하위 폴더 단위로 둘 수 있고, 현재 작업 위치에 더 가까운 파일의 지침이 더 구체적인 기준이 된다.

1. AGENTS.md에는 "일하는 방식"을 적는다

좋은 AGENTS.md는 철학 문서가 아니라 작업 매뉴얼이다. 코덱스가 코드를 읽고, 고치고, 검증할 때 바로 쓸 수 있는 정보가 들어가야 한다.

예를 들어 다음 항목은 효과가 크다.

• 프로젝트 구조와 중요한 디렉터리

• 설치, 빌드, 테스트, 린트 명령

• 코드 스타일과 기존 패턴

• 건드리면 안 되는 파일이나 위험한 작업

  3. 위치별로 역할을 나눈다

  전역 AGENTS.md에는 개인 선호를 둔다. 예를 들어 답변 길이, 보고 방식, 위험 명령을 다루는 기준 같은 것이다.

  저장소 루트의 AGENTS.md에는 팀이 공유해야 하는 규칙을 둔다. 프로젝트 구조, 테스트 명령, 배포 금지선, 리뷰 기준이 여기에 맞다.

  하위 폴더의 AGENTS.md에는 예외를 둔다. 예를 들어 apps/web은 접근성 테스트를 요구하고, packages/api는 마이그레이션 파일을 직접 수정하지 말라는 식이다. 이렇게 나누면 한 파일이 비대해지지 않고, 작업 위치에 맞는 지침만 강해진다.

  4. 완료 기준을 문장으로 고정한다

  바이브코딩에서 가장 중요한 줄은 "무엇을 만들라"보다 "무엇으로 끝났다고 판단할지"다.

  완료 기준:
  - 변경 파일을 요약한다.
  - 실행한 테스트, 린트, 타입체크 결과를 적는다.
  - 실행하지 못한 검증은 이유와 남은 위험을 적는다.
  - 사용자 변경으로 보이는 unrelated diff는 되돌리지 않는다.

  이런 문장이 있으면 코덱스가 임의로 작업을 넓히거나, 검증 없이 완료 보고를 하는 일이 줄어든다.

  5. 두 번 반복된 실수만 규칙으로 만든다

  AGENTS.md는 길어질수록 힘이 약해진다. 한 번 난 실수는 프롬프트로 처리하고, 두 번 반복된 실수는 규칙으로 올리는 방식이 좋다.

  예를 들어 코덱스가 테스트 없이 완료했다고 말한 일이 반복되면 "검증하지 못하면 완료라고 말하지 않는다"를 추가한다. SVG 파일을 자주 깨뜨리면 "이미지는 저장 후 브라우저나 뷰어로 확인한다"를 추가한다. 이렇게 실제 마찰에서 출발한 규칙은 오래 살아남는다.

  Senior takeaway: AGENTS.md는 코덱스에게 주는 팀의 작업 계약서다. 반복 프롬프트를 줄이고, 검증 기준을 고정하고, 위험한 작업의 경계를 명확히 하면 코덱스는 단발성 채팅 도구가 아니라 저장소의 작업 습관을 따르는 에이전트가 된다.

• PR 또는 완료 보고에 포함할 내용

• 어떤 검증을 통과해야 끝난 것으로 볼지

공식 베스트 프랙티스 문서도 AGENTS.md를 팀의 빌드, 테스트, 리뷰, 출하 방식에 맞게 편집하라고 안내한다. 핵심은 "길게"가 아니라 "실행 가능하게"다.

2. 처음에는 짧은 규칙부터 시작한다

처음부터 모든 것을 쓰려고 하면 금방 낡은 문서가 된다. 코덱스가 실제로 자주 틀리는 것부터 넣는 편이 좋다.

검증:
- UI 변경 후에는 관련 테스트 또는 화면 확인을 실행한다.
- 검증하지 못한 경우 완료라고 말하지 말고 이유를 적는다.

제한:
- 요청하지 않은 대규모 리팩터링은 하지 않는다.
- 비밀값, 쿠키, 토큰은 출력하지 않는다.

이 정도만 있어도 코덱스의 기본 동작이 달라진다. 매번 "검증해줘"라고 덧붙이지 않아도 작업 끝에 증거를 남기는 방향으로 움직인다.