AGENTS.md 한 줄로 해결하는 Claude Code 장문 보고서 액션 아이템 상단 배치 팁

Claude Code나 Codex가 긴 작업을 마친 뒤 출력하는 장문 보고서에서 사용자에게 필요한 조치 사항이 본문 중간에 묻히지 않도록, 'Lead with what you need from me' 규칙을 AGENTS.md에 추가해 가장 시급한 차단 작업을 최상단 번호 매김 목록으로

tau · 2026년 10월 6일

#Claude Code #AGENTS.md #Prompt Engineering #Developer Experience #Codex

AGENTS.md 한 줄로 해결하는 Claude Code 장문 보고서 액션 아이템 상단 배치 팁

AI 개발자 Vox(@Voxyz_ai)가 2026년 10월 6일, Claude Code나 Codex 등 자율형 코딩 에이전트가 긴 작업을 완료한 뒤 출력하는 방대한 텍스트 보고서에서 사용자가 수행해야 할 핵심 조치 사항이 본문 중간에 파묻히지 않도록 방지하는 간결한 AGENTS.md 지침 규칙을 공개했습니다.

Claude Code의 AGENTS.md 설정에 액션 아이템 상단 배치 규칙(Lead with what you need from me)을 추가한 코드 에디터 화면 예시

이미지 출처: @Voxyz_ai (X)

Claude Code 같은 에이전트 툴체인이 복잡한 리팩토링이나 다단계 빌드, 테스트 디버깅 등의 작업을 수행한 뒤에는 실행 로그, 코드 변경 내역, 분석 결과가 포함된 긴 텍스트(Wall of Text)를 한꺼번에 출력하는 경우가 흔합니다. 이 과정에서 결제 콘솔 로그인, API 키 발급, 특정 CSV 파일 배치 등 개발자가 즉시 처리해 주어야 에이전트가 다음 작업으로 넘어갈 수 있는 필수 액션 아이템이 본문 중간이나 긴 스크롤 끝자락에 묻혀버려 작업 흐름이 지연되는 문제가 자주 발생합니다.

1. AGENTS.md에 추가하는 'Lead with what you need from me' 규칙

해결책은 프로젝트 루트의 에이전트 지침 파일인 AGENTS.md에 다음 단일 섹션을 명시하는 것입니다.

## 7. Lead with what you need from me
When a long task is done, or you're stuck and need me to do something, list what you need from me at the very top of your reply. One thing per item, numbered. Spell out what I should do, where, and what to send back to you when I'm done, e.g. "Log into Stripe, export the September refunds CSV, put it in inbox/". Whatever's blocking you most goes first. If you don't need anything from me, just say so.

이 규칙은 에이전트의 응답 생성 순서와 정보 우선순위를 다음과 같이 구체적으로 강제합니다.

  • 최상단 즉시 보고: 긴 작업이 끝났거나 작업 도중 진행이 막혀 사용자의 개입이 필요할 때, 장문 본문보다 먼저 답변 맨 위에 사용자 요청 사항을 배치합니다.
  • 단일 작업 단위 번호 매김: 항목당 하나의 작업만 번호를 매긴 목록(Numbered list)으로 작성해 한눈에 인지할 수 있도록 합니다.
  • 3대 행동 요소 명시: 사용자가 무엇을(What) 해야 하는지, 어느 경로/위치(Where)에서 해야 하는지, 그리고 작업을 마친 후 에이전트에게 무엇을 전달(Send back)해야 하는지를 구체적으로 명시합니다 (예: "Stripe에 로그인하고, 9월 환불 내역 CSV를 내보내어 inbox/ 디렉토리에 넣으세요").
  • 최대 차단 요소 우선 정렬(Blocker First): 에이전트의 진행을 가장 심각하게 가로막고 있는 병목 작업을 목록의 가장 첫 번째 항목으로 배치합니다.
  • 불필요 시 명시적 선언: 사용자 측의 조치가 전혀 필요 없는 작업이라면, 필요한 것이 없다고 명확히 한 줄로 밝히고 본문 보고서로 넘어갑니다.

2. 6대 에이전트 기본 규칙 체계와의 결합

이번 팁은 앞서 공개된 개발자 6대 AGENTS.md 핵심 원칙에 7번째 규칙으로 추가된 구성입니다.

  1. Plan before you touch code: 코드 수정 전 계획 수립
  2. Smallest change that works: 동작하는 최소 단위의 변경 적용
  3. Split work across subagents: 서브에이전트 간 작업 분할
  4. Own the bug: 발생한 버그에 대한 책임 완수
  5. Verify before you say done: 완료를 선언하기 전 철저한 자체 검증
  6. Write down every correction: 수정 사항의 문서화 및 피드백 기록
  7. Lead with what you need from me: 사용자 조치 사항 최상단 배치

기존 6개 원칙이 에이전트의 내부 실행 품질(계획, 최소 변경, 검증)을 규정했다면, 7번째 원칙은 에이전트가 작업을 마친 뒤 인간 개발자와 만나는 접점(Handoff)에서의 커뮤니케이션 오버헤드를 제거하는 역할을 합니다.

3. 실무 적용 시 고려 사항과 피드백

커뮤니티 논의와 실무 적용 시 확인된 주요 포인트는 다음과 같습니다.

  • 단순 서식보다 '차단 순서' 지정이 핵심: 피드백에 참여한 개발자들은 "가장 심각하게 막고 있는 요소를 최상단에 두라(Whatever's blocking you most goes first)"는 문장이 단순한 불릿 포인트 서식 지침보다 실질적인 워크플로우 단축 효과가 크다고 평가했습니다.
  • 태스크 이해도와의 연계 필요성: 에이전트가 작업의 맥락이나 근본 원인을 충분히 파악하지 못한 경우, 피상적인 작업만 상단에 나열하고 실제 근본 문제는 여전히 본문에 남겨둘 위험이 있습니다. 따라서 명확한 작업 범위 정의와 병행되어야 효과가 극대화됩니다.
  • Claude Code 및 다중 에이전트 환경 적용: Claude Code는 2.1.277 버전 이후 AGENTS.md를 프로젝트 지침으로 지원하며, CLAUDE.md 내에서 @AGENTS.md를 임포트해 단일 진실 공급원(SSOT)으로 동기화할 수 있습니다. 이를 통해 Codex, Claude Code 등 여러 에이전트 툴체인 전반에 동일한 보고 규약을 일관되게 적용할 수 있습니다.

원문 출처