에이전트가 소극적인 건 성격 문제가 아니라 지시문 문제입니다. 어디서 멈춰야 할지를 알려주지 않으면, 에이전트는 가장 안전한 지점 — 첫 번째 답변 — 에서 멈춥니다.
대상: 로컬 VS Code에서 Claude Code를 쓰는 개발자 목적: 매번 확인받지 않고 한 번의 지시로 끝까지 진행시키기
1. 에이전트가 멈추는 세 지점
능동성을 설계하려면 먼저 어디서 멈추는지를 알아야 합니다. 실제로 멈추는 이유는 딱 세 가지입니다.
멈추는 이유증상해결 위치
| 완료 조건이 없다 |
"리팩터링 해줘"에는 끝이 없음. 설명 한 편 쓰고 턴을 넘김 |
지시문 |
| 권한에서 막힌다 |
파일 수정·명령 실행마다 승인 대기 → 자율 진행이 아니라 20번의 클릭 |
권한 설정 |
| 애매해서 되묻는다 |
선택지가 갈리는 지점에서 진행 대신 질문을 택함 |
지시문(판단 기준) |
아래 다섯 요소는 이 세 지점을 지시문 안에서 미리 막아두는 방법입니다.
2. 능동적 요청문의 다섯 요소
순서는 상관없지만, 다섯 개가 다 있으면 에이전트는 되묻지 않고 끝까지 갑니다.
2-1. 목표 — 행동이 아니라 "상태"로 쓴다
"~를 해줘"는 한 번의 행동으로 끝납니다. "~인 상태로 만들어"는 그 상태가 될 때까지 반복하게 만듭니다. 이 한 끗 차이가 능동성의 대부분을 결정합니다.
- ❌ 테스트 고쳐줘
- ✅ npm test가 전부 통과하는 상태로 만들어
2-2. 완료 판정 — 에이전트가 직접 실행할 수 있는 검증 명령을 준다
사람이 눈으로 확인하는 기준 말고, 터미널에서 참/거짓이 나오는 기준을 주세요. 그래야 에이전트가 자기 작업을 스스로 채점하고 다시 시도합니다.
완료 기준: npm run lint, npm run build, npm test 세 개가 모두 exit 0.
2-3. 중단 규칙 — "멈추지 마"와 "여기선 멈춰"를 함께 준다
중간 확인을 금지하되, 진짜 위험한 예외는 명시적으로 열어두세요. 예외를 안 주면 에이전트는 불안해서 계속 되묻거나, 반대로 건드리면 안 되는 걸 건드립니다.
중간에 확인 요청하지 말고 끝까지 진행해. 단 운영 DB 접근 · git push --force · 시크릿 파일 수정은 실행 전에 반드시 멈추고 물어봐.
2-4. 판단 기준 — 갈림길에서 쓸 기본값을 미리 준다
"애매하면 물어봐"는 곧 중단입니다. 대신 "애매하면 이렇게 해"를 주면 진행됩니다. 가정 세우는 걸 막지 말고, 대신 나중에 보고하게 하세요.
판단이 갈리면 기존 코드 스타일을 따르는 쪽으로 결정하고, 세운 가정은 마지막에 목록으로 보고해.
2-5. 작업 범위 — 마음대로 해도 되는 영역을 못 박는다
범위가 열려 있으면 에이전트는 조심스러워집니다. 자유 영역과 금지 영역을 같이 주면 그 안에서는 확실히 능동적으로 움직입니다.
src/**, tests/** 안에서는 파일 생성·삭제·수정 다 알아서 해. migrations/, .env*, package-lock.json은 손대지 마.
2-6. (보너스) 보고 — 끝에 무엇을 받을지 정한다
보고 형식을 지정하면 에이전트가 중간 설명을 줄이고 실행에 집중합니다. 진행 중 수다가 줄어드는 부수 효과도 큽니다.
진행 중 설명은 최소로. 끝나면 변경 파일 목록 / 세운 가정 / 남은 리스크 세 항목만 보고해.
3. 같은 일, 다른 지시문 (Before / After)
사례 A. 버그 수정
❌ 멈추는 지시문
로그인 API에 버그 있는 것 같은데 좀 봐줘.
범위·완료조건·권한이 전부 비어 있음. 에이전트는 코드를 읽고 "이런 것 같습니다" 리포트를 쓰고 멈춥니다.
✅ 끝까지 가는 지시문
로그인 API에서 만료 토큰이 401 대신 500을 반환하는 버그를 재현부터 수정까지 끝내줘.
1) 실패하는 테스트를 먼저 작성해서 재현하고
2) 원인을 고치고
3) npm test가 전부 통과할 때까지 반복해.
src/auth/**, tests/** 안에서는 알아서 수정해.
중간 확인 없이 진행하고, 끝나면 변경 파일과 원인 한 줄만 보고해.
상태 목표 + 검증 명령 + 범위 + 중단 금지. 재현 → 수정 → 검증 루프가 지시문 안에 들어 있습니다.
사례 B. 리팩터링
❌ 멈추는 지시문
"리팩터링"은 끝이 없는 동사입니다. 어디까지가 완료인지 모르니 한두 개만 고치고 "이런 것도 가능합니다"로 끝납니다.
✅ 끝까지 가는 지시문
src/services 아래에서 200줄 넘는 파일이 하나도 없는 상태로 만들어줘.
먼저 대상 파일 목록과 분리 계획을 세우고, 승인 기다리지 말고 바로 실행해.
각 파일을 쪼갤 때마다 npm test를 돌려서 초록이면 다음 파일로 넘어가.
빨간불이면 최대 3번까지 스스로 고쳐보고, 그래도 안 되면 그 파일만 원복하고 목록에 남겨줘.
공개 API 시그니처는 바꾸지 마.
측정 가능한 완료 조건(200줄), 파일 단위 검증 루프, 실패 시 재시도 횟수와 폴백까지 지정.
사례 C. 의존성 업그레이드
❌ 멈추는 지시문
이 라이브러리 최신 버전으로 올려줄 수 있어?
가능 여부를 묻는 문장은 가능 여부에 대한 답을 받습니다. 게다가 breaking change 앞에서 반드시 멈춥니다.
✅ 끝까지 가는 지시문
axios를 최신 메이저로 올리고 빌드·테스트가 통과하는 상태로 만들어줘.
CHANGELOG의 breaking change를 먼저 확인하고, 우리 코드에서 영향받는 호출부를 전부 찾아서 고쳐.
마이그레이션 방법이 여러 개면 공식 문서 권장안을 택하고 이유를 마지막에 한 줄로 적어줘.
작업은 upgrade/axios 브랜치에서 하고, 커밋은 하되 push는 하지 마.
기본 판단 기준(공식 권장안)을 미리 주어 되묻기를 차단하고, 위험한 동작(push)만 명시적으로 금지.
4. 지시문만으로 안 되는 부분: 권한
지시문을 아무리 잘 써도 승인 프롬프트가 뜨면 거기서 멈춥니다. 자율 진행의 실질적인 병목은 대개 여기입니다.
수단어디서효과
| 자동 승인 토글 |
VS Code 확장 입력창 |
편집 승인을 매번 누르지 않아도 됨. 가장 손쉬운 첫 단계 |
| /permissions |
세션 중 명령 |
허용/거부 규칙을 눈으로 보며 추가. 여기서 정한 값이 설정 파일에 남음 |
| --permission-mode |
CLI 실행 시 |
plan은 계획만, acceptEdits는 파일 편집 자동 승인. 지원 값은 claude --help로 확인 |
| --allowedTools |
CLI 실행 시 |
"Bash(npm test),Read,Edit"처럼 필요한 것만 미리 열기. 가장 안전한 자동화 형태 |
| claude -p "..." |
터미널·스크립트 |
대화 없이 한 번에 실행. cron, git hook, CI에 붙일 때 사용 |
⚠️ 주의 — 모든 검사를 건너뛰는 모드(bypassPermissions 계열)는 사내 코드베이스에서 기본값으로 쓰지 마세요. 자유 영역을 지시문으로 좁히고 --allowedTools로 필요한 도구만 여는 쪽이 훨씬 안전하면서 체감 속도는 같습니다.
5. 매번 쓰지 말고 한 번만 박아두기 (CLAUDE.md)
다섯 요소 중 중단 규칙 · 판단 기준 · 작업 범위 · 보고 형식은 매 요청마다 달라지지 않습니다. 프로젝트 루트의 CLAUDE.md에 넣어두면 모든 세션에 자동 적용되고, 지시문은 목표와 완료 조건 두 줄로 짧아집니다.
markdown
# 작업 방식
- 작업은 계획 → 실행 → 검증 순서로 진행하고, 중간 확인 요청 없이 끝까지 간다.
- 완료 전 반드시 `npm run lint`와 `npm test`를 직접 실행해 통과를 확인한다.
- 테스트가 실패하면 최대 3회까지 스스로 수정하고, 그래도 안 되면 시도한 내용과 함께 보고한다.
- 판단이 갈리면 기존 코드 스타일과 기존 패턴을 따르는 쪽을 택하고, 세운 가정은 마지막에 목록으로 보고한다.
- 진행 중 설명은 최소로 한다. 완료 보고는 변경 파일 / 가정 / 남은 리스크 세 항목.
# 손대면 안 되는 것
- `migrations/`, `.env*`, `package-lock.json` 수정 금지
- `git push --force`, 운영 DB 접근은 실행 전 반드시 확인
이렇게 해두면 평소 요청은 이 정도로 줄어듭니다.
결제 취소 API에서 중복 취소가 막히는 상태로 만들어줘.
6. 이벤트에 자동으로 반응시키기 (Hooks)
지시문은 사람이 말을 걸어야 시작됩니다. 훅은 말을 걸지 않아도 특정 시점에 무조건 실행되는 규칙입니다. 프롬프트로 "저장하면 린트 돌려줘"라고 부탁하는 것보다 확실합니다.
훅 이벤트시점주 용도
| SessionStart |
세션이 열릴 때 |
환경 변수 로드, 브랜치 확인 등 준비 작업 |
| PreToolUse |
도구 실행 직전 |
위험한 명령을 실제로 차단할 수 있는 유일한 지점 |
| PostToolUse |
파일 편집 직후 |
포매터·린터·타입체크 자동 실행 |
| Stop |
응답이 끝난 뒤 |
요약 기록, 자동 커밋 등 마무리 |
.claude/settings.json 예시 — 파일을 편집할 때마다 prettier와 eslint를 자동 실행:
json
{
"hooks": {
"PostToolUse": [
{
"matcher": "Edit|Write",
"hooks": [
{
"type": "command",
"command": "npx prettier --write \"$CLAUDE_FILE_PATHS\" && npx eslint --fix \"$CLAUDE_FILE_PATHS\"",
"timeout": 60
}
]
}
]
}
}
- 훅 스크립트는 stdin으로 이벤트 JSON을 받고, 종료 코드로 결과를 알립니다.
- PreToolUse에서 exit 2를 반환하면 그 도구 호출이 차단됩니다.
- 팀 공통 규칙은 .claude/settings.json(커밋), 개인 설정은 .claude/settings.local.json(gitignore)에 둡니다.
- 이벤트 이름과 필드는 버전에 따라 늘어나므로, 적용 전 공식 훅 레퍼런스에서 현재 스키마를 확인하세요.
7. 반복되는 요청은 아예 명령으로 만든다
- 슬래시 커맨드 — .claude/commands/fix-tests.md에 다섯 요소를 다 갖춘 지시문을 저장해두면, 다음부터는 /fix-tests 한 단어로 같은 품질의 요청이 나갑니다. $ARGUMENTS로 인자를 받을 수 있습니다.
- 서브에이전트 — .claude/agents/*.md의 description에 "코드를 수정한 뒤에는 반드시 먼저 사용"처럼 언제 쓰는지를 적어두면, 사용자가 호출하지 않아도 Claude가 알아서 위임합니다. 능동성의 상당 부분이 이 한 줄에서 나옵니다.
- /loop — 배포 상태나 CI처럼 "될 때까지 지켜봐야 하는" 일은 세션 안에서 주기적으로 다시 확인하게 할 수 있습니다.
- GitHub Actions — PR·이슈처럼 사람이 자리에 없을 때 발생하는 이벤트는 anthropics/claude-code-action으로 넘기는 게 맞습니다. 로컬 VS Code 세션이 할 일이 아닙니다.
8. 복붙 템플릿
새 작업을 시킬 때 이 골격만 채우면 됩니다. CLAUDE.md를 이미 세팅했다면 앞의 두 항목만 써도 충분합니다.
[목표] ______가 ______인 상태로 만들어줘.
[완료] 다음이 모두 통과하면 완료야: ______, ______
[절차] 1) ______ 2) ______ 3) 검증이 실패하면 최대 3회까지 스스로 고쳐
[범위] ______ 안에서는 알아서 수정해. ______는 손대지 마.
[진행] 중간 확인 요청 없이 끝까지 진행해.
단 ______는 실행 전에 멈추고 물어봐.
판단이 갈리면 ______ 쪽으로 결정하고 가정은 마지막에 보고해.
[보고] 끝나면 변경 파일 / 세운 가정 / 남은 리스크만 알려줘.
9. VS Code 확장에서의 주의점
- 입력창의 자동 승인 토글이 체감상 가장 큰 차이를 만듭니다. 여기부터 켜보세요.
- 훅, 서브에이전트, 슬래시 커맨드, CLAUDE.md는 확장에서도 그대로 동작합니다. 설정 파일은 프로젝트의 .claude/ 아래에 두면 됩니다.
- claude -p 같은 비대화형 자동화는 터미널 CLI 쪽입니다. cron이나 git hook에 물릴 작업은 확장이 아니라 CLI로 실행하세요.
