1장. 작업 정의와 에이전트 지시

학습 목표

• 막연한 기능 요청을 관찰할 수 있는 완료 기준이 붙은 작업 지시로 고쳐 쓴다.
• 큰 기능을 하나씩 실행하고 검증하고 되돌릴 수 있는 작은 작업으로 나눈다.
• 작업의 불확실성과 영향 범위를 보고 계획을 먼저 받을지 바로 맡길지 고른다.
• 에이전트가 내놓은 계획을 검토해 불필요한 단계를 빼고 범위를 조정한다.
• 저장소 지침 파일(AGENTS.md·CLAUDE.md·GEMINI.md)에 넣을 내용과 다른 장치로 옮길 내용을 구분한다.

들어가며

어느 금요일 저녁, 1인 창업자가 코딩 에이전트에게 "회원가입을 좀 더 매끄럽게 해 줘"라고 맡기고 저녁을 먹으러 나갔습니다. 돌아와 보니 에이전트는 "작업을 완료했습니다"라는 보고와 함께 폼 디자인, 비밀번호 규칙, 패키지 목록까지 바꿔 두었습니다. 무엇이 좋아졌고 무엇이 망가졌는지 판단할 기준이 없어 결국 전부 되돌렸습니다.

에이전트가 무능해서 생긴 일이 아닙니다. 에이전트는 받은 지시 안에서 성실히 일했고, '다 된 것처럼 보이는' 순간에 멈췄습니다. 문제는 지시에 끝이 어디인지, 어디까지 건드려도 되는지, 무엇으로 결과를 증명할지가 없었다는 데 있습니다.

이 장은 일을 맡기는 쪽의 기술을 다룹니다. 먼저 완료 기준과 좋은 작업 지시의 구조를 익히고, 큰 기능을 작게 나누는 법과 기존 코드의 방식을 따르게 하는 법을 봅니다. 이어서 언제 계획을 먼저 받고 그 계획을 어떻게 검토하는지, 매번 반복할 말을 저장소 지침 파일에 담는 법을 배웁니다. 깊이 읽기에서는 규칙이 정해지지 않은 기능과 사람이 지켜보지 않는 작업을 다룹니다.

핵심 개념

일을 맡긴다는 것

코딩 에이전트에게 일을 시켜도 결과의 책임은 사람에게 남습니다. 지시하는 사람이 챙길 몫은 네 가지입니다.

1. 목표 정하기: 무엇을 왜 만드는지, 끝이 어디인지 정합니다.
2. 계획 검토하기: 에이전트가 택한 방법이 목표와 범위에 맞는지 봅니다.
3. 결과 확인하기: 보고가 아니라 증거로 결과를 판단합니다(2장).
4. 내놓을지 판단하기: 기록하고(3장), 위험을 점검하고(4장), 사용자에게 내놓을지 결정합니다(5장).

Claude Code 모범 사례 문서는 이 관계를 한 문장으로 설명합니다. 에이전트는 일이 '다 된 것처럼 보일 때' 멈추고, 스스로 돌려 볼 검사가 없으면 '그렇게 보인다'는 것이 유일한 신호가 된다는 것입니다. 그때는 사람이 검증 담당이 되어 모든 실수를 직접 찾아야 합니다. 인테리어 업체에 "거실을 예쁘게"라고만 말하면 결과가 마음에 들지 않아도 따질 근거가 없는 것과 같습니다. "벽은 흰색, 조명은 따뜻한 색 두 개, 붙박이장은 그대로"라고 말하면 다 됐을 때 하나씩 확인할 수 있습니다.

완료 기준: '끝'을 미리 정하기

완료 기준(definition of done)은 일이 끝났는지를 누가 확인해도 같은 결론이 나오도록 미리 적어 둔 조건입니다. 좋은 완료 기준은 화면을 보거나 명령을 돌려 맞는지 틀리는지 판정할 수 있습니다. "좋게", "깔끔하게", "빠르게" 같은 형용사는 사람마다 기준이 달라 완료 기준이 되지 못합니다.

완료 기준은 두 종류로 나누어 쓰면 빠뜨리는 것이 줄어듭니다. 기능 기준은 무엇이 동작해야 하는지("별점 4를 누르면 4점 후기만 보인다"), 품질 기준은 어떤 조건을 지켜야 하는지("기존 테스트가 모두 통과한다", "새 패키지를 추가하지 않는다", "좁은 화면에서도 깨지지 않는다")입니다.

Claude Code 모범 사례는 완료 기준을 에이전트가 직접 돌릴 수 있는 검사로 주라고 권합니다. 예시 입력과 기대 결과를 몇 개 적고 "구현한 뒤 테스트를 돌려라"라고 쓰면, 에이전트가 검사를 통과할 때까지 스스로 고칩니다.

좋은 작업 지시의 네 요소

좋은 작업 지시에는 보통 네 가지가 들어갑니다. 작은 계약서라고 생각하면 됩니다.

1. 목표: 무엇을 만드는가. 사용자가 무엇을 할 수 있게 되는가.
2. 완료 기준: 무엇이 확인되면 끝인가.
3. 범위와 금지: 어디까지 건드려도 되고, 무엇은 손대면 안 되는가.
4. 검증 방법: 어떤 명령이나 확인 절차로 끝을 증명하고, 무엇을 증거로 보여 줄 것인가.

목표: 주문 내역 화면에서 '배송 중' 주문만 골라 보는 필터를 추가한다.
완료 기준:
- 필터에서 '배송 중'을 고르면 상태가 배송 중인 주문만 보인다.
- '전체'를 고르면 원래 목록으로 돌아온다.
- 위 두 경우를 확인하는 테스트를 추가하고 npm test 가 모두 통과한다.
범위와 금지:
- src/pages/orders/ 안의 파일만 바꾼다.
- 주문 데이터 구조와 결제 관련 코드는 바꾸지 않는다. 새 패키지를 설치하지 않는다.
검증 방법:
- 실행한 테스트 명령과 출력 전체, 360px 너비의 화면 캡처를 보여 준다.

네 요소가 모두 있으면 지시가 짧아도 됩니다. 반대로 형용사를 열 줄 늘어놓아도 완료 기준과 범위가 없으면 결과를 판단할 수 없습니다.

화면 한 장 밖의 상태까지 정하기

기능을 설명할 때 사람들은 보통 모든 것이 잘된 화면 하나를 떠올립니다. 하지만 실제 앱은 그 화면에 이르기까지 여러 상태를 지나갑니다. 지시에 이 상태들이 없으면 에이전트가 알아서 정하거나 아예 빠뜨립니다.

상태를 빠짐없이 찾는 요령은 사용자 흐름(user flow)을 먼저 그려 보는 것입니다. 사용자가 어디서 들어와 무엇을 누르고 어디서 끝나는지 순서대로 적고, 각 단계에서 "이때 데이터가 없으면? 느리면? 실패하면? 중간에 나가면?"을 묻습니다. 이 질문에서 나온 답이 곧 완료 기준이 됩니다.

작게 쪼개기: 세로로 자르기

맡기는 일이 클수록 바뀌는 파일이 늘고, 검토가 어려워지며, 문제가 생겼을 때 어느 변경 탓인지 찾기 힘듭니다. 그래서 큰 기능은 작은 작업으로 나눠 맡깁니다. 이때 나누는 방향이 중요합니다.

케이크를 생각해 보세요. 층별로 나누면(시트만, 크림만, 과일만) 한 조각을 다 만들 때까지 아무도 맛을 볼 수 없습니다. 세로로 자르면 조각마다 모든 층이 들어 있어 첫 조각부터 맛을 볼 수 있습니다. 작업도 같습니다.

세로로 자른 작업은 각자 독립적으로 실행하고, 검증하고, 되돌릴 수 있습니다. 작업이 적당한 크기인지는 두 가지로 판단합니다. 바뀐 내용을 한 문장으로 설명할 수 있는가, 그리고 한 번 앉은 자리에서 검토를 끝낼 수 있는가. 이삿짐 상자마다 내용물을 적어 두듯 '한 작업 = 한 목적'으로 나누면 확인과 되돌리기가 쉬워집니다.

Anthropic의 장기 실행 에이전트 실험에서도 세션마다 기능 하나씩만 맡긴 것이 결정적이었고, 기능마다 커밋을 남겨 문제가 생기면 이전 상태로 돌아갈 수 있게 했습니다.

기존 방식을 가리켜 맡기기

에이전트는 같은 기능을 만드는 방법을 여러 개 압니다. 지시에 아무 말이 없으면 그중 하나를 고르는데, 그것이 이 저장소의 방식과 다를 수 있습니다. 오류 형식, 입력 검사 방법, 컴포넌트 구조가 파일마다 제각각이 되면 앱은 점점 고치기 어려워집니다.

해결책은 따라야 할 예를 직접 가리키는 것입니다. Claude Code 모범 사례도 기존 파일 하나를 좋은 예로 지목해 그 방식을 따르게 하고, 이미 쓰는 것 외에는 라이브러리를 쓰지 말라고 범위를 정하라고 권합니다. 에이전트가 이 저장소의 실제 코드를 기준으로 삼게 되므로 긴 설명보다 효과가 큽니다.

src/api/products.ts 가 입력을 검사하고 오류를 돌려주는 방식을 먼저 읽어라.
같은 방식으로 src/api/coupons.ts 에 쿠폰 조회 API를 만든다.
이미 package.json 에 있는 패키지만 쓴다.

계획 먼저 받기

처음 보는 코드에 여러 파일이 얽힌 기능을 붙일 때는 에이전트가 곧바로 코드를 쓰게 하기보다 먼저 계획을 받는 편이 안전합니다. 계획 단계에서 바꿀 파일, 작업 순서, 손대지 않을 범위를 미리 확인하고 조정할 수 있기 때문입니다. 계획을 고치는 비용은 코드를 되돌리는 비용보다 훨씬 쌉니다.

Claude Code 모범 사례는 탐색, 계획, 구현, 커밋의 네 단계를 권합니다. 탐색과 계획은 plan mode에서 합니다. plan mode는 파일을 읽고 읽기 전용 명령으로 탐색하지만 소스 파일은 고치지 않는 모드로, Shift+Tab을 눌러 상태 표시줄에 plan mode가 켜졌다고 나올 때까지 전환하거나 claude --permission-mode plan으로 세션을 시작합니다. 받은 계획은 Ctrl+G로 텍스트 편집기에서 직접 고친 뒤 진행시킬 수 있습니다. 계획을 승인하거나 다시 Shift+Tab으로 모드를 바꾸면 구현 단계로 넘어갑니다.

다른 도구에도 비슷한 장치가 있습니다. Gemini CLI는 --approval-mode에 plan 값을 둡니다. 계획 모드가 없는 도구에서도 "먼저 계획만 세우고 파일은 고치지 마라"라고 요청할 수는 있지만, 이 말은 권한을 바꾸지 않으므로 파일 수정을 실제로 막지는 못합니다. 막아야 한다면 계획 모드나 읽기 전용 권한을 씁니다.

계획을 검토하는 다섯 질문

그럴듯한 단계 목록이 곧 좋은 계획은 아닙니다. 계획을 받으면 다음 다섯 가지를 차례로 묻습니다.

1. 요구와 이어지는가: 단계마다 어느 요구를 위한 것인지 짝지을 수 있는가? 짝이 없는 단계는 범위 밖일 가능성이 큽니다.
2. 범위를 넘는가: 금지한 파일이나 관계없는 정리 작업("하는 김에 공통 컴포넌트도 정리")이 끼어 있지 않은가?
3. 되돌리기 어려운 일이 있는가: 기존 데이터를 일괄 수정하거나, 데이터베이스 구조를 바꾸거나, 외부로 메일을 보내는 단계가 있는가? 있다면 그 단계만 따로 떼어 확인합니다.
4. 검증 단계가 있는가: 계획 끝에 어떤 검사로 무엇을 확인할지 적혀 있는가?
5. 크기가 맞는가: 작은 요구에 비해 계획이 지나치게 크지 않은가? 새 라이브러리 도입, 폴더 구조 변경처럼 요구에 없던 큰 결정이 숨어 있지 않은가?

검토 결과는 구체적으로 돌려줍니다. "3단계는 빼라. 기존 회원 데이터는 바꾸지 않는다", "5단계 앞에 테스트 작성 단계를 넣어라"처럼 단계 번호와 이유를 함께 말하면 에이전트가 정확히 고칩니다.

저장소 지침 파일: 도구마다 읽는 방식

저장소(repository)는 프로젝트의 파일과 변경 기록을 담는 폴더입니다. 저장소에 두는 지침 파일은 세션을 시작할 때마다 에이전트가 먼저 읽는 안내 메모로, 팀이 같은 말을 되풀이하지 않게 해 줍니다. 신입 직원에게 건네는 업무 안내서와 비슷합니다.

여러 도구를 함께 쓰는 팀은 내용을 한 파일로 관리하고 싶어 합니다. Claude Code 문서는 CLAUDE.md와 AGENTS.md가 함께 있으면 기본적으로 CLAUDE.md만 읽는다고 설명하고, 한 파일을 공유하려면 CLAUDE.md 맨 위에 @AGENTS.md라고 적어 가져오라고 안내합니다. 개인 설정에서 두 파일을 함께 읽게 하는 값(claude-md-and-agents-md)을 고를 수도 있습니다. @경로는 Claude Code의 가져오기 문법이고, Gemini CLI도 GEMINI.md에서 @파일 가져오기를 지원합니다. Codex는 ~/.codex/config.toml의 project_doc_fallback_filenames로 다른 이름의 지침 파일을 인정하게 할 수 있습니다.

@AGENTS.md

## Claude Code 전용
- src/billing/ 아래를 바꿀 때는 plan mode로 계획부터 보여 준다.

지침이 실제로 읽혔는지는 확인할 수 있습니다. Claude Code에서는 /context로 불러온 파일을 보고, Gemini CLI는 /memory show로 합쳐진 내용을 보여 줍니다. Codex 문서는 에이전트에게 지침을 요약해 보라고 시켜 읽은 순서를 확인하는 방법을 소개합니다.

지침 파일에 무엇을 넣을까

기준은 하나입니다. 코드만 읽어서는 알 수 없는데, 모르면 실수하게 되는 것만 넣습니다. Claude Code 모범 사례는 줄마다 "이 줄을 지우면 에이전트가 실수할까?"라고 묻고, 아니라면 지우라고 합니다. 지침이 길어지면 정작 중요한 규칙이 묻혀 무시되기 때문입니다.

분량도 관리합니다. Claude Code 문서는 CLAUDE.md 한 파일을 200줄 아래로 유지하라고 권합니다. 그보다 길어지는 내용은 성격에 따라 다른 자리로 옮깁니다.

@경로 가져오기는 긴 파일을 정리하는 데는 도움이 되지만, 가져온 파일도 세션 시작 때 함께 올라가므로 분량을 줄여 주지는 않습니다. 처음 지침 파일을 만들 때는 Claude Code의 /init(코드베이스를 분석해 초안을 만들고, 이미 있으면 개선점을 제안) 같은 초안 생성 명령으로 시작한 뒤, 코드에서 알 수 없는 내용을 사람이 보충합니다.

깊이 읽기

규칙이 아직 없는 기능: 인터뷰와 명세

완료 기준을 쓰려 해도 쓸 수 없는 때가 있습니다. 예약 자리가 나면 대기자에게 몇 분 동안 우선권을 줄지, 응답이 없으면 다음 사람에게 넘길지 같은 업무 규칙이 아직 정해지지 않은 경우입니다. 이때 에이전트에게 바로 구현을 맡기면 에이전트가 빈칸을 그럴듯한 추측으로 채우고, 그 추측이 코드 곳곳에 퍼집니다.

Claude Code 모범 사례는 큰 기능일수록 에이전트가 먼저 사람을 인터뷰하게 하라고 권합니다. 짧은 설명만 주고 AskUserQuestion 도구로 자세히 질문하게 하되, 뻔한 질문은 빼고 구현 방식, 화면, 경계 사례, 걱정거리, 선택지의 장단점처럼 사람이 미처 생각하지 못한 어려운 부분을 파고들게 합니다. 질문이 끝나면 결과를 SPEC.md 같은 명세 파일로 쓰게 합니다.

좋은 명세는 그 자체로 완결됩니다. 관련 파일과 인터페이스를 이름으로 적고, 하지 않을 일을 밝히고, 기능 전체가 동작함을 증명하는 처음부터 끝까지의 확인 절차로 끝납니다. 명세가 완성되면 새 세션에서 구현을 시작합니다. 인터뷰 과정의 긴 대화가 남지 않은 깨끗한 맥락에서, 명세 파일만 기준으로 일하게 하기 위해서입니다. 문서도 명세를 다듬는 데 쓴 시간이 구현을 지켜보는 시간보다 값지다고 말합니다.

인터뷰는 사람의 사각지대를 드러내는 데도 쓸모가 있습니다. "대기자 두 명이 거의 동시에 수락하면?", "우선권 시간 안에 수업이 취소되면?" 같은 질문은 운영자가 스스로 놓친 경우를 찾게 합니다. 다만 규칙을 결정하는 것은 여전히 사람의 몫입니다.

컨텍스트라는 예산

에이전트가 한 대화에서 참고하는 모든 내용(메시지, 읽은 파일, 명령 출력)을 컨텍스트(context)라고 합니다. 컨텍스트에는 한도가 있고, Claude Code 문서는 컨텍스트가 찰수록 앞서 받은 지시를 잊거나 실수가 늘 수 있다며 이를 가장 중요한 관리 자원이라고 부릅니다.

그래서 지침 파일은 짧게 유지하고(세션마다 올라가므로), 관계없는 일 사이에는 /clear로 맥락을 비웁니다. 한 작업을 하다 엉뚱한 질문을 하고 돌아오는 '잡동사니 세션'이 가장 흔한 낭비입니다. 수십 개 파일을 훑는 조사는 하위 에이전트(subagent)에게 맡깁니다. 하위 에이전트는 별도의 컨텍스트에서 파일을 읽고 요약만 돌려주므로 구현 중인 대화의 맥락이 보존됩니다.

사람이 지켜보지 않는 작업

밤새 맡겨 두거나, 수백 개 파일에 같은 변경을 일괄 적용하거나, 클라우드에서 도는 에이전트에게 맡기는 작업에는 중간에 질문에 답할 사람이 없습니다. 이런 작업일수록 지시가 완결되어 있어야 합니다.

일괄 작업은 순서가 중요합니다. Claude Code 모범 사례가 소개하는 방법은 이렇습니다. 바꿀 대상의 목록부터 파일로 뽑고, 비대화형 실행(claude -p "지시")을 대상마다 부르는 스크립트를 쓰되, 전체를 돌리기 전에 두세 개로 시험해 보고 거기서 드러난 문제에 맞춰 지시를 고칩니다. 필요한 도구는 --allowedTools로 미리 허용하고, --permission-mode dontAsk를 주어 원래라면 승인을 물었을 호출은 묻지 않고 거절되게 합니다(작업 폴더 안 파일 읽기처럼 승인이 필요 없는 일은 그대로 실행됩니다). --max-turns로 반복 횟수에 상한을 두면 한 대상에서 헤매는 실행도 멈춥니다. 작은 시험으로 실수를 먼저 걸러 내야 같은 실수가 대상 전체로 번지지 않습니다.

클라우드 에이전트도 같습니다. Codex의 클라우드 환경 설정에는 의존성 설치 스크립트, 환경 변수와 비밀값, 인터넷 접근 허용 여부와 도메인 범위를 정하는 항목이 있습니다. 테스트에 필요한 것은 미리 준비하되 접근은 필요한 만큼만 엽니다.

실무 장면

골목책방: 열한 개 파일을 되돌린 뒤

동네 서점 '골목책방' 사장 윤서는 독자 후기 게시판에 별점 필터를 붙이고 싶었다. 처음에 "후기 페이지 좀 개선해 줘"라고 맡겼더니 에이전트는 디자인, 정렬, 작성 폼까지 파일 열한 개를 고쳤다. 무엇이 맞게 됐는지 판단할 수 없어 윤서는 모두 되돌렸다.

두 번째에는 네 요소를 갖춰 다시 썼다.

1. 목표: 후기 목록 위에 별점(1~5) 필터 버튼을 둔다.
2. 완료 기준: 별점 4를 누르면 별점 4인 후기만 보이고, '전체'를 누르면 모두 보인다. 해당 별점의 후기가 없으면 "아직 이 별점의 후기가 없습니다"가 보인다. 세 경우를 확인하는 테스트를 추가하고 npm test가 통과해야 끝이다.
3. 범위와 금지: 후기 목록 화면만 바꾼다. 후기 작성 폼과 데이터베이스 구조는 바꾸지 않는다.
4. 검증: 테스트 출력과 브라우저 화면 캡처를 보여 준다.

윤서는 처음에 빈 상태를 빠뜨렸다가 사용자 흐름을 그려 보며 추가했다. 별점 2를 누르는 손님이 있을 텐데, 2점 후기가 하나도 없다면 빈 화면이 뜰 것이었다.

바뀌는 파일이 여러 개일 것 같아 plan mode로 계획부터 받았다. 계획에는 "후기 표에 별점 색인을 추가한다"는 단계가 있었다. 윤서는 다섯 질문으로 계획을 훑었다. 이 단계는 어느 요구와도 짝지어지지 않았고(질문 1), 데이터베이스를 손대는 일이라 금지한 범위에 걸렸으며(질문 2), 후기가 200개 남짓이라 화면에서 걸러도 충분했다(질문 5). 윤서는 그 단계를 빼고 화면에서 걸러 내게 했다.

에이전트는 테스트 출력과 화면 캡처를 보여 줬고, 윤서는 브라우저에서 직접 눌러 본 뒤 받아들였다. 두 시도의 차이는 에이전트의 능력이 아니라 지시의 구조였다. 완료 기준이 멈출 지점을 알려 줬고, 범위가 계획의 불필요한 단계를 걸러 냈다.

파도소리 서핑스쿨: 큰 기능을 세로로 자르기

강습 예약 앱을 운영하는 '파도소리 서핑스쿨' 대표 도윤은 "파도가 위험한 날 강습이 취소되면 예약자에게 알리고 환불까지 처리하는 기능"을 만들고 싶었다. 기능은 관리자 화면, 예약 데이터, 문자 발송, 결제 환불에 걸쳐 있었다.

도윤이 처음 떠올린 방법은 세 가지였다.

• 한 번에 맡기기: 지시 한 번이면 끝날 것 같았다. 하지만 바뀔 파일이 스무 개가 넘을 것이고, 환불이 잘못 나가도 어느 변경 탓인지 찾기 어려웠다. 기각했다.
• 층별로 나누기: 데이터 구조, 서버, 화면 순서로 맡기는 방법이다. 세 작업이 끝날 때까지 실제로 동작하는 것이 없어 중간 확인이 불가능했다. 기각했다.
• 세로로 자르기: 사용자가 쓸 수 있는 결과 단위로 나누는 방법이다. 이것을 골랐다.

도윤은 먼저 규칙이 덜 정해졌다는 점을 깨달았다. 강습 두 시간 전에 취소되면 전액 환불인지, 대체 강습을 고를 수 있는지 정하지 않았다. 그래서 에이전트에게 먼저 인터뷰를 맡겼고, "이미 대체 강습을 고른 사람에게도 문자를 보내는가?" 같은 질문에 답하며 규칙을 정해 SPEC.md로 남겼다.

그리고 세 작업으로 잘랐다.

1. 관리자가 강습을 '기상 취소'로 바꾸면 예약자 목록 화면에 취소 표시가 뜬다. 문자와 환불은 아직 하지 않는다.
2. 기상 취소가 되면 예약자에게 안내 문자가 한 번만 나간다. 테스트에서는 실제 발송 대신 발송 기록만 남긴다.
3. 예약자가 안내 링크에서 '환불'을 고르면 결제 취소 요청이 나가고 예약 상태가 '환불 완료'로 바뀐다.

작업마다 새 세션에서 SPEC.md를 기준으로 맡겼다. 결제 코드를 건드리는 세 번째 작업만 plan mode로 계획을 받았고, 계획에 "결제 모듈의 공통 오류 처리를 정리한다"는 단계가 끼어 있는 것을 보고 범위 밖이라며 뺐다. 첫 작업이 끝난 날부터 관리자는 실제로 취소 표시를 쓸 수 있었다. 세 번째 작업에서 환불 금액 계산 실수가 나왔을 때도, 바로 앞 작업까지는 이미 검증된 상태라 원인을 세 번째 작업의 변경 안에서만 찾으면 됐다.

자주 틀리는 지점

1. "길게 자세히 쓸수록 좋은 지시다." 길이가 정확성을 만든다고 느끼기 쉽습니다. 하지만 형용사를 열 줄 늘어놓아도 확인할 조건이 없으면 결과를 판단할 수 없습니다. 짧더라도 완료 기준, 범위, 검증 방법이 분명한 지시가 낫습니다.
2. "지침 파일에 적어 두면 에이전트가 반드시 지킨다." 파일에 적힌 규칙은 규칙처럼 보입니다. 하지만 지침은 에이전트가 판단에 참고하는 자료일 뿐이라, 내용이 길거나 앞뒤가 맞지 않으면 빠뜨리는 줄이 생깁니다. 꼭 막아야 하는 행동은 권한 규칙이나 훅 같은 강제 장치에 맡깁니다.
3. "신중하려면 모든 작업을 계획부터 받아야 한다." 신중함은 미덕이지만, 계획이 효과를 내는 것은 불확실하고 큰 작업입니다. 한 문장으로 설명되는 수정까지 계획을 받으면 시간만 듭니다.
4. "한 번에 많이 맡기면 왕복이 줄어 효율적이다." 지시 횟수만 보면 그렇습니다. 하지만 줄어든 왕복보다 늘어난 검토 시간과 되돌리기 비용이 큽니다. 문제가 생기면 큰 묶음 전체를 버려야 할 수도 있습니다.
5. "기능을 나눌 때는 데이터, 서버, 화면 순으로 나누는 것이 정석이다." 기술 구조를 따라 나누면 깔끔해 보입니다. 하지만 마지막 층이 끝날 때까지 동작을 확인할 수 없습니다. 사용자가 할 수 있는 일 단위로 세로로 자릅니다.
6. "에이전트가 계획을 세웠으니 계획은 믿어도 된다." 그럴듯한 단계 목록은 설득력이 있습니다. 하지만 계획에는 요구에 없던 정리 작업, 되돌리기 어려운 데이터 변경, 빠진 검증 단계가 섞여 있을 수 있습니다. 다섯 질문으로 검토한 뒤 승인합니다.

한눈에 정리

공식 문서로 확인하기

• Claude Code: Best practices — 검증 수단 주기, 탐색→계획→구현→커밋, 계획을 건너뛸 때, 인터뷰와 명세, 일괄 실행
• Claude Code: How Claude remembers your project — CLAUDE.md 위치와 불러오는 순서, @ 가져오기, .claude/rules/, AGENTS.md 처리
• Claude Code: Skills — 스킬 파일 위치와 disable-model-invocation
• Codex: Custom instructions with AGENTS.md — AGENTS.md 탐색 순서, 크기 한도, 대체 파일 이름
• Gemini CLI: GEMINI.md — 지침 파일 계층, @ 가져오기, /memory, context.fileName
• Anthropic: Effective harnesses for long-running agents — 기능 하나씩 맡기기와 진행 기록 남기기

셀프 체크

1-1. 두 요청이 있다. (가) "알림 설정 화면을 쓰기 편하게 다듬어 줘" (나) "알림을 끄면 다음 날 아침 요약 메일이 오지 않고, 설정 화면을 새로고침해도 꺼진 상태가 유지된다". 어느 쪽에 완료 기준이 있는가? 다른 쪽은 어떻게 고쳐 쓰겠는가?

1-2. 손님의 지난 예약 내역을 보여 주는 목록 화면을 맡기려 한다. 모든 것이 잘된 화면 말고 지시에 함께 적어야 할 상태 네 가지를 들고, 각각 완료 기준을 한 줄씩 써 보라.

1-3. 공방 체험 예약 앱에 '단체 예약 문의' 기능을 붙이려 한다. 문의 폼, 관리자 확인 화면, 접수 안내 메일이 필요하다. 이 기능을 세로로 자른 작업 세 개로 나누고, 작업마다 완료 기준을 하나씩 붙여 보라.

1-4. Claude Code의 plan mode에서 받은 계획 가운데 한 단계의 표현만 직접 고친 뒤 진행시키고 싶다. 어떤 키를 쓰는가? 또 plan mode를 거치지 않고 바로 맡겨도 되는 작업의 예를 하나 들라.

1-5. 상품 상세 화면에 '재입고 알림 신청' 버튼을 추가하는 계획을 받았다. 단계는 ① 신청 버튼과 신청 완료 문구 추가 ② 신청 내역을 저장하는 API 추가 ③ 앱 전체 버튼 컴포넌트의 색과 여백 정리 ④ 작업 완료 보고였다. 다섯 질문으로 보면 이 계획의 문제는 무엇이고, 어떻게 고치라고 돌려주겠는가?

1-6. 저장소에는 팀이 쓰는 AGENTS.md만 있고, Claude Code는 이 파일을 잘 읽고 있었다. 한 팀원이 개인 메모를 담은 CLAUDE.local.md를 루트에 만들자 그 팀원의 세션에서만 팀 규칙이 지켜지지 않기 시작했다. 왜 그런지, 해결 방법은 무엇인지 설명하라.

1-7. 팀이 에이전트용 지침을 TEAM_GUIDE.md 한 파일로 관리하기로 했다. Codex와 Gemini CLI가 각각 이 파일을 지침으로 읽게 하려면 어떤 설정을 바꾸는가?

실습 과제