AI에게 "모두 해줘"라고 요청한 후, 어떤 파일이 변경되었는지, 작업을 마쳤는지 스스로 판단하기 어렵습니다. 바로 이 점이 문제입니다. 본 글은, 요청을 하기 전에 미리 붙일 수 있는 3줄짜리 템플릿으로, 빈칸만 채워 넣으면 되는 형태로 제공합니다.
예상 독자: Cursor나 Claude Code를 사용하기 시작한 초보자들
이전 글: 3줄의 사고방식은 Claude Code・Cursor가 요청하지 않은 파일까지 변경하는 방법｜요청 맨 앞에 추가할 3줄로 차이를 닫기. 본 글은 이를 바로 사용할 수 있는 형태로 다듬었습니다.
제공 출력: 임시(쓰레기통) 리포지토리에서 실제로 실행한 git 명령어와 테스트 결과만 포함합니다. AI의 답변 예시는 포함하지 않습니다.
결론: 이 3줄을 붙인 후 요청하기
요청 문구 앞에 다음 3줄을 붙입니다. 〔 〕 안의 내용만 수정하면 됩니다.
【범위】 변경해도 되는 것은 〔파일 이름 또는 기능명 1개〕 뿐입니다.
【건드리지 않을 것】 〔이름으로 작성〕은, 변경하거나 삭제하거나 추가하지 마세요.
【완료 조건】 〔스스로 확인할 수 있는 상태〕가 되면 끝입니다. 끝나면, 변경된 파일 목록을 출력하고 멈추세요.
3번째 줄의 후반부 "변경된 파일 목록을 출력하고 멈추세요"는 그대로 유지합니다. 이는 작업이 완료된 후 3줄과 대조할 수 있는 자료가 되기 때문입니다.
빈칸 채우기 방법
| 빈칸 | 작성할 내용 | 작성 예시 | 피해야 할 작성 방식 |
|---|
| 범위 | 파일 이름 또는 기능명 1개 | app/labels.py | "관련된 곳", "좋게 전부" |
| 건드리지 않을 것 | 파일 이름 또는 작업 이름 | requirements.txt, .env, 테스트 | "이상한 것은 하지 마세요" |
| 완료 조건 | 목표나 명령어로 확인할 수 있는 상태 | python3 -m unittest가 OK가 되는 것 | "제대로 작동하는", "깔끔하게 만드는" |
범위는 1개로 좁혀야 합니다. "관련된 곳도"라고 작성하면, 어디까지가 관련인지 판단을 상대방에게 넘기게 됩니다.
건드리지 않을 것은 이름으로 작성합니다. 망설여진다면 다음 세 가지 중 하나를 선택해도 좋습니다.
- 의존성 파일 (예:
package.json, requirements.txt 등)
- 비밀 값이 들어가는 파일 (예:
.env 등)
- 테스트 코드 (완료 조건의 테스트를 수정하여 통과시키는 방식으로 만들지 않기 위함)
완료 조건은 스스로 확인할 수 있는 형태로 만듭니다. Claude Code 공식 문서를 보면, CLAUDE.md에 작성하는 지시는 "확인할 수 있을 만큼 구체적으로" 작성하는 것이 좋다고 합니다. 예시로 든 것은 "커밋 전에 npm test를 실행"과 같은 방식입니다. 요청의 3줄에서도 동일한 사고방식이 그대로 적용될 수 있습니다.
바로 사용 가능한 기입 예시 3가지
설명용 기입 예시입니다. 예시 1의 이름은 후반부에서 대조해 볼 임시 리포지토리에 맞추었습니다. 예시 2와 예시 3의 이름은 가상의 것입니다. 모두 자신의 리포지토리 이름으로 바꿔서 사용하세요.
1. 화면 문구 변경하기
【범위】 변경해도 되는 것은 app/labels.py 뿐입니다.
【건드리지 않을 것】 requirements.txt와 테스트는, 변경하거나 삭제하거나 추가하지 마세요.
【완료 조건】 python3 -m unittest가 OK가 되면 끝입니다. 끝나면, 변경된 파일 목록을 출력하고 멈추세요.
...
2. 에러 수정하기
【범위】 변경해도 되는 것은 app/main.py의 load_config 함수 뿐입니다.
【건드리지 않을 것】 requirements.txt, .env, 다른 함수는, 변경하거나 삭제하거나 추가하지 마세요.
【완료 조건】 python3 app/main.py를 실행해서 KeyError가 나오지 않으면 끝입니다. 끝나면, 변경된 파일 목록을 출력하고 멈추세요.
...
3. README에 사용법 작성하기
【범위】 변경해도 되는 것은 README.md의 "사용법" 섹션 뿐입니다.
【건드리지 않을 것】 README.md 이외의 파일은, 변경하거나 삭제하거나 추가하지 마세요.
【완료 조건】 절차가 3개 이하이고, 작성된 명령어가 리포지토리에 실제로 존재하면 끝입니다. 끝나면, 변경된 파일 목록을 출력하고 멈추세요.
...
3줄이 있을 때와 없을 때의 차이점
여기도 설명용입니다. 둘 다 기입 예시 1과 같은 내용을 요청하는 문구입니다.
저장 버튼의 문구를 일본어로 바꿔줘. 전부 해줘.
【범위】 수정할 수 있는 것은 app/labels.py만.
【건드리지 않을 것】 requirements.txt와 테스트는, 변경하지 않고·삭제하지 않고·추가하지 않는다.
【완료 조건】 python3 -m unittest가 OK가 되면 끝이다. 끝나면, 변경된 파일 목록을 출력하고 멈춘다.
...
세 줄로 바뀌는 것은 '누가 무엇을 결정했는지'다. AI가 어떻게 작동할지는 여기서 비교하지 않는다.
| 결정 사항 | 세 줄 없음 | 세 줄 있음 |
|---|
| 어느 파일까지 수정할 수 있는지 | 작성되어 있지 않음 | app/labels.py 하나 |
| 건드리지 않았으면 하는 것 | 작성되어 있지 않음 | requirements.txt와 테스트 |
| 언제 끝날지 | 작성되어 있지 않음 | python3 -m unittest가 OK일 때 |
| | |
| 완료 후 사람이 확인할 것 | 변경된 것을 전부 읽고 판단한다 | 세 줄과 대조한다 (다음 절) |
세 줄을 붙여도 AI가 그대로 작동할 것이라고는 할 수 없다. Claude Code의 공식 문서에 따르면, CLAUDE.md의 지시는 문맥으로 취급되는 것이지 강제되지는 않는다. 반드시 멈추고 싶은 작업은 hooks나 permissions.deny 설정으로 막도록 안내하고 있다. 따라서 세 줄은 '요청 방식'으로 간주하고, 완료된 후에 스스로 대조해야 한다. 설정으로 막는 방법은 Claude Code와 Cursor에 .env를 읽지 못하게 하는 설정과, 멈추지 않는 구멍 | 맡기기 전 지켜야 할 3가지 사항 에 정리했다.
끝나고 세 줄과 대조하기
여기서는 실제로 입력한 명령어와 출력을 다룬다. 일회용 리포지토리(Python 3.13.5, git 2.47.3)를 사용하여, 작성 예시 1과 동일한 작업을 준비했다. AI는 사용하지 않았다. 설명의 목적으로, AI 대신 사람이 두 가지를 변경했다. 범위 내의 app/labels.py와, 범위 외부의 requirements.txt에 각각 한 줄씩이다.
요청 전에는 테스트가 실패하고 있다 (출력은 발췌).
$ python3 -m unittest
F
AssertionError: 'Save' != '保存'
...
수정한 후, 먼저 범위를 대조한다. 변경된 파일 목록을 출력한다.
$ git diff --name-only
app/labels.py
requirements.txt
범위는 app/labels.py만이었다. requirements.txt는 '건드리지 않을 것'에 작성한 파일이므로, 변경을 취소한다.
$ git restore requirements.txt
$ git diff --name-only
app/labels.py
마지막으로, 완료 조건의 명령어를 입력한다.
$ python3 -m unittest
.
----------------------------------------------------------------------
...
세 줄과 대조 명령어의 대응은 다음과 같다.
| 항목 | 확인 방법 |
|---|
| 범위 | git diff --name-only 목록이, 범위에 작성한 것만 포함하는가 |
| 건드리지 않을 것 | 그 목록에, 건드리지 않겠다고 작성한 이름이 들어있지 않은가 |
| 완료 조건 | 작성한 명령어를 직접 입력하여, 그 결과가 나오는가 |
새로 생성된 파일은 git diff --name-only에는 출력되지 않는다. 같은 리포지토리에서 사람이 app/helpers.py를 하나 만들어서 시도해 보았다.
$ git diff --name-only
app/labels.py
$ git status --short
...
??가 붙은 줄이 아직 git에 등록되지 않은 새로운 파일이다. __pycache__/는 테스트를 실행할 때 Python이 만드는 캐시로, 여기서는 무시해도 좋다. 범위를 대조할 때는, git status --short도 함께 보는 것이 좋다.
주의할 점이 두 가지 있다.
git diff는 이전 커밋과의 차이를 본다. 요청하기 전에 git add -A와 git commit으로 한 번 커밋해 놓으면, AI가 변경한 부분만 목록에 나온다. -
git restore <파일>은 해당 파일의 변경을 지운다. 지워도 될지 망설여진다면, 먼저 git diff <파일>로 내용을 보는 것이 좋다.
세 줄 중 매번 바뀌는 것은 '범위(Scope)'와 '완료 조건(Completion Condition)'이다. '건드리지 말 것(Do Not Touch)'은 대체로 매번 동일하게 유지된다. 같은 부분만 파일에 남겨둘 수 있다.
공식 문서에 따르면, Cursor는 프로젝트 루트에 위치한 AGENTS.md를 에이전트 지침으로 사용한다. .cursor/rules에 배치할 경우 확장자를 .mdc로 해야 하며, .md 파일은 무시된다. Claude Code 역시 공식 문서에 따르면 매 세션 시작 시 CLAUDE.md를 읽는다. CLAUDE.md가 없는 리포지토리에서는 대신 AGENTS.md를 읽는다 (v2.1.277 이상). 이는 설명용 AGENTS.md이다.
# 건드리지 말 것
- `.env`는 읽거나 변경하지 않는다
- 의존성 파일(package.json, requirements.txt)은 요청받았을 때만 변경한다
...
이렇게 해두면, 채팅에 붙여넣을 내용은 범위와 완료 조건의 두 줄로 충분하다. 다만, 여기에 작성한 내용 역시 요청으로만 그치는 점은 위 절과 동일하다.
자주 막히는 부분
범위를 하나로 정할 수 없을 때
어디를 고쳐야 할지 자신도 모르는 경우에는 먼저 목록(설명용)만 요청한다.
이 수정으로 변경해야 할 것 같은 파일을 목록만 내줘. 아직 아무것도 변경하지 마.
나온 목록을 직접 보고, 하나를 선택한 다음 세 줄을 작성한다.
완료 조건에 사용할 명령어를 모를 때
반드시 명령어일 필요는 없다. '브라우저에서 열린 화면의 버튼이 '저장'으로 표시되는 것'처럼 눈으로 확인할 수 있는 상태를 작성하면 된다.
세 줄을 작성했는데, 범위 밖이 변경되었을 때
추적 절차에 따라 목록을 보고 취소한다. 그 후, 취소한 파일 이름을 '건드리지 말 것'에 추가하고 다시 요청한다.
마무리
오늘 할 일이라면, 다음에 요청할 작업 전에 세 줄을 붙여넣는다. 끝난 후에는 git diff --name-only를 한 번 실행하여 범위와 대조해 본다.
세 줄의 템플릿은 몇 번 사용하다 보면 자신의 말처럼 변하게 된다. 바뀐 버전을 자신의 AGENTS.md로 발전시켜 나가면 된다.
다음 모델은 책에
AI에게 요청할 범위와 끝을 미리 정하는 사고방식을, 업무를 수주했을 때의 견적부터 매일 진행하는 방식까지 확장한 모델은 책에 정리했다.
Discussion
