코딩 에이전트가 일을 제대로 하고 있는지 더 쉽게 모니터링하기 위한 룰 (+ 실제 실험 기록)

"나날이 발전하고픈 개발자를 위한 AI 활용법" 슬라이드에 담았던 내용이기도 하지만, AI 시대에는 코드뿐 아니라 코드를 만든 프롬프트도 함께 관리할 필요가 있습니다. 이게 있으면 코딩 에이전트가 뭘 하고 있는지 내가 인지하기 위한 투명성도 훨씬 높아지죠.

오늘 비개발자 친구를 과외해주면서, "내부 구조와 동작 원리를 이해하지 못한 상태에서 바이브 코딩을 하다 보니 현재 상태를 파악하지 못하고, 직접 컨트롤하지 못한다는 게 상당히 고통스럽다"는 얘기를 들었어요. 몰라도 목적지까지 도달할 수 있으면 괜찮은데 그게 아니라서요.

그래서 이 모니터링을 돕기 위한 프롬프트(CLAUDE.md나 Cursor 룰로 만들 만한)를 즉석에서 구상해봤습니다.

**IMPORTANT**: <MUST_FOLLOW_RULE>
매번 채팅할 때마다, /__prompts 폴더에
- 내가 채팅한 기록과 너의 (툴 호출, 코드 스니펫 등 빼고) 의견을 파일로 저장해줘 (ex: 250818-0001-chat.md)
- 그 채팅으로 인해 구현을 하게 되면 그 구현 계획도 같이 저장해줘 (ex: 250818-0001-plan.md)

그리고 유의미한 구현 하나가 끝날 때마다 
- 비개발자 입장에서 이 작업이 제대로 됐는지, 되어가고 있는지 직접 확인할 만한 방법을 얘기해줘. 그 내용도 같이 저장해줘. (ex: 250818-0001-test.md)
- 위 모든 문서들과 함께 커밋을 자동으로 해줘.
</MUST_FOLLOW_RULE>

이런 내용으로 시작하되, 위 가이드를 번역해서 영어로 만들어두고, 문서 안의 내용은 한글로 한다거나... 같은 이야기를 나눴어요. 이렇게 하면 커밋별로 이 문서들만 살펴봐도 진행상황을 확인하고, 필요시 되돌아가기도 더 쉬울 것 같아서요.

저도, 이 친구도 앞으로 이런 방식으로 구현을 좀 해보려고 합니다.

참고로 __prompts 는 __로 시작하니 커밋된 파일들 중 가장 위쪽에 위치할 것이고, 알파벳 순서상 chat > plan > test 이니 확인할 순서도 잘 맞습니다.

실험 시작: 클로드 코드와 문답

위 내용을 토대로 클로드 코드와 대화를 나눈 뒤, 첫번째 구현을 해봤습니다.

그 결과는 다음과 같습니다. (사실 날짜 입력이 이상하게 되는 문제가 있어서 한번 더 핑퐁을 하긴 했습니다)

250818-0001-prompt-version-control-chat.md

# Chat History: Prompt Version Control Implementation
Date: 2025-08-18
Feature: prompt-version-control

## User Request #1
이런 내용의 룰을 추가하려고 해.

---
**IMPORTANT**: <MUST_FOLLOW_RULE>
매번 채팅할 때마다, /__prompts 폴더에
- 내가 채팅한 기록과 너의 (툴 호출, 코드 스니펫 등 빼고) 의견을 파일로 저장해줘 (ex: 250818-0001-chat.md)
- 그 채팅으로 인해 구현을 하게 되면 그 구현 계획도 같이 저장해줘 (ex: 250818-0001-plan.md)

그리고 유의미한 구현 하나가 끝날 때마다 
- 비개발자 입장에서 이 작업이 제대로 됐는지, 되어가고 있는지 직접 확인할 만한 방법을 얘기해줘. 그 내용도 같이 저장해줘. (ex: 250818-0001-test.md)
- 위 모든 문서들과 함께 커밋을 자동으로 해줘.
</MUST_FOLLOW_RULE>
---

AI 시대에는 코드뿐 아니라 코드를 만든 프롬프트와 컨텍스트도 버전관리해야 한다는 생각을 담았어. 이 내용 자체는 영어로 만들되, 각 문서 안에 들어가는 내용은 원본 그대로 하고, 테스트 방법은 한글로 쓰는 걸 고려하고 있어.

당장 이걸 구현하기 위해 파일을 수정할 필요는 없고. 어떻게 생각하는지 듣고 싶어.

## AI Response #1
이 아이디어는 정말 흥미롭고 선견지명이 있네요. AI 기반 개발에서 "프롬프트가 곧 소스코드"라는 관점이 인상적입니다.

**장점:**
- **투명성**: 코드가 어떤 요청과 맥락에서 생성됐는지 추적 가능
- **재현성**: 동일한 프롬프트로 비슷한 결과 도출 가능
- **학습 자료**: 팀원들이 효과적인 프롬프트 작성법 학습
- **비개발자 친화적**: 테스트 문서로 진행상황 확인 가능

**고려사항:**
1. **파일명 체계**: `YYMMDD-NNNN` 형식은 좋지만, 브랜치나 기능별 prefix 추가도 고려 (ex: `feat-login-250818-0001`)
2. **자동화 트리거**: "유의미한 구현"의 기준 정의 필요 (TodoWrite 완료 시점?)
3. **민감정보**: 프롬프트에 API 키나 개인정보 포함 여부 체크
4. **.gitignore**: 임시 실험용 프롬프트는 제외 옵션

이런 접근은 "AI-Native Development"의 좋은 예시가 될 것 같습니다.

## User Request #2
- 파일명 체계에서 유의미한 기능 또는 요청사항을 명시하는 게 좋겠네. YYMMDD-NNNN-feature.md 이런 식으로.
- 자동화 트리거는 일단 ToDoWrite 완료 시점으로 하자. 근데 그러면 hook으로 되어야 하나?
- 민감정보 지적 잘 해줬네. 민감정보라고 판단이 되면 `****`으로 표시해야겠어.
- 임시 프롬프트도 일단은 포함하자. 내 뇌의 일부 스냅샷을 넣고 싶은 거니까.

## AI Response #2
네, 좋은 방향입니다! 정리해보면:

**개선된 파일명 체계:**
```
YYMMDD-NNNN-{feature-slug}-chat.md
YYMMDD-NNNN-{feature-slug}-plan.md  
YYMMDD-NNNN-{feature-slug}-test.md
```
예: `250818-0001-add-prompt-tracking-chat.md`

**자동화 트리거:**
- TodoWrite 완료 시점이 좋은 선택입니다
- Hook보다는 제가 직접 TodoWrite 상태 변경 시 트리거하는 게 나을 것 같습니다 (hook은 외부 의존성 추가)
- "모든 todos가 completed" 되면 자동 커밋

**민감정보 마스킹:**
```markdown
// 원본: NEXT_PUBLIC_SUPABASE_URL=https://xyz.supabase.co
// 저장: NEXT_PUBLIC_SUPABASE_URL=****
```

"뇌의 스냅샷"이라는 표현이 정말 적절하네요. 생각의 흐름과 시행착오까지 모두 자산이 되는 거죠.

## User Request #3
좋아. 지금까지의 내용을 이 룰의 첫 사례로써 /__prompts에 저장해줘.

250818-0001-prompt-version-control-plan.md

# Implementation Plan: Prompt Version Control System
Date: 2025-08-18
Feature: prompt-version-control

## Objective
Implement a system to track and version control AI development prompts alongside code, treating prompts as "source code" in the AI development era.

## Implementation Steps

### 1. Directory Structure Setup
- [x] Create `__prompts/` directory in project root
- [ ] Add directory to version control

### 2. File Naming Convention
Implement naming pattern: `YYMMDD-NNNN-{feature-slug}-{type}.md`
- YYMMDD: Date stamp
- NNNN: Sequential number for the day
- feature-slug: Descriptive feature identifier
- type: chat, plan, or test

### 3. Document Types
For each feature implementation:
- **chat.md**: Complete conversation history (prompts + AI responses, excluding tool calls)
- **plan.md**: Technical implementation strategy
- **test.md**: Non-technical verification steps in Korean

### 4. Automation Rules
- Trigger: When all TodoWrite items marked as "completed"
- Actions:
  1. Generate all three document types
  2. Mask sensitive information with `****`
  3. Auto-commit with descriptive message

### 5. CLAUDE.md Integration
Add the following rule section:
```markdown
## Prompt & Context Version Control

<MUST_FOLLOW_RULE>
Track AI development context in `/__prompts/` directory:

1. **File naming**: `YYMMDD-NNNN-{feature-slug}-{type}.md`
2. **Required files per feature**:
   - `-chat.md`: User prompts + AI responses (tool calls excluded)
   - `-plan.md`: Implementation strategy
   - `-test.md`: Non-technical verification steps (Korean)
3. **Sensitive data**: Mask with `****`
4. **Auto-commit**: When all todos marked complete
5. **Include all prompts**: Even experimental ones (brain snapshots matter)
</MUST_FOLLOW_RULE>
```

## Benefits
1. **Traceability**: Track which prompts generated which code
2. **Reproducibility**: Recreate similar results with same prompts
3. **Knowledge Sharing**: Team learning from effective prompts
4. **Non-technical Visibility**: Progress tracking for stakeholders

## Success Criteria
- [ ] __prompts directory created and tracked
- [ ] First set of prompt documents generated
- [ ] CLAUDE.md updated with new rules
- [ ] Auto-commit functionality working
- [ ] Sensitive data properly masked

250818-0001-prompt-version-control-test.md

# 테스트 및 확인 방법: 프롬프트 버전 관리 시스템
날짜: 2025-08-18
기능: prompt-version-control

## 비개발자를 위한 확인 방법

### 1. 폴더 구조 확인
**확인 방법:**
1. 프로젝트 루트에서 `__prompts` 폴더를 찾아보세요
2. 이 폴더 안에 다음 3개 파일이 있는지 확인:
   - `250818-0001-prompt-version-control-chat.md` (대화 기록)
   - `250818-0001-prompt-version-control-plan.md` (구현 계획)
   - `250818-0001-prompt-version-control-test.md` (이 파일)

**예상 결과:** 3개 파일이 모두 존재해야 함

### 2. 대화 기록 파일 확인
**확인 방법:**
1. `chat.md` 파일을 열어보세요
2. 우리가 나눈 대화가 순서대로 기록되어 있는지 확인

**예상 결과:** 
- "AI 시대에는 코드뿐 아니라..." 로 시작하는 첫 질문이 있어야 함
- AI의 답변이 함께 기록되어 있어야 함
- 코드나 기술적인 명령어는 제외되어 있어야 함

### 3. 구현 계획 파일 확인
**확인 방법:**
1. `plan.md` 파일을 열어보세요
2. 체크박스로 된 작업 목록이 있는지 확인

**예상 결과:**
- 구현 단계가 명확히 정리되어 있어야 함
- 파일명 규칙, 자동화 규칙 등이 설명되어 있어야 함

### 4. CLAUDE.md 파일 업데이트 확인
**확인 방법:**
1. 프로젝트 루트의 `CLAUDE.md` 파일을 열어보세요
2. 파일 맨 아래쪽에 "Prompt & Context Version Control" 섹션이 추가되었는지 확인

**예상 결과:**
- 새로운 규칙이 영문으로 추가되어 있어야 함
- `<MUST_FOLLOW_RULE>` 태그로 감싸진 내용이 있어야 함

### 5. Git 커밋 확인
**확인 방법:**
1. GitHub Desktop이나 SourceTree 같은 Git 도구를 열어보세요
2. 최근 커밋 목록을 확인

**예상 결과:**
- "Implement prompt version control system" 같은 커밋 메시지가 있어야 함
- `__prompts/` 폴더의 파일들과 `CLAUDE.md` 파일이 함께 커밋되어 있어야 함

### 6. 민감정보 마스킹 확인
**확인 방법:**
1. 저장된 파일들을 열어서 API 키나 비밀번호 같은 정보를 찾아보세요

**예상 결과:**
- 민감한 정보는 `****`로 표시되어 있어야 함
- 실제 값이 노출되어 있으면 안 됨

## 성공 기준 체크리스트
- [ ] `__prompts` 폴더가 생성됨
- [ ] 3개의 문서 파일이 모두 생성됨 (chat, plan, test)
- [ ] 파일명이 날짜-번호-기능명 형식을 따름
- [ ] CLAUDE.md에 새 규칙이 추가됨
- [ ] 모든 변경사항이 Git에 커밋됨

## 문제 해결
만약 위 사항들이 확인되지 않는다면:
1. 프로젝트 폴더를 새로고침 해보세요
2. Git 상태를 다시 확인해보세요
3. 파일 탐색기에서 숨김 파일 표시 옵션을 켜보세요

추가 문답

이렇게 하고 나서, 이녀석이 얘기해준 테스트 플랜대로 하나씩 살펴보니 CLAUDE.md 내용이 좀 빈약하다는 게 느껴졌습니다. 그래서 (CLAUDE.md를 잘 따르는지 테스트도 할 겸) 새로운 세션을 열어서 다시 요청을 넣었습니다. 그런데 재미있게도 이 과정에서는 __prompts 에 기록을 담지 않고 있더군요. 그래서 또다시 얘기를 나눴습니다.

250818-0002-claude-md-improvement-chat.md

# Chat History: CLAUDE.md Prompt Recording Rules Improvement
Date: 2025-08-18
Feature: claude-md-improvement

## User Request #1
CLAUDE.md에서, 프롬프트를 기록할 때 민감정보 마스킹에 대한 내용이 제대로 들어가지 않은 것 같아.
@__prompts/250818-0001-prompt-version-control-chat.md 을 참고해서 CLAUDE.md를 수정해줘.
민감정보 마스킹 외에도 수정할 건 더 없는지도 봐줘.

## AI Response #1
__prompts/250818-0001-prompt-version-control-chat.md 파일을 확인했습니다. CLAUDE.md의 민감정보 마스킹 섹션을 더 구체적으로 업데이트하겠습니다.

수정 완료했습니다:
1. **민감정보 마스킹 섹션 개선**: 구체적인 예시와 마스킹 대상 항목들을 추가
2. **chat.md 설명 보완**: "code snippets excluded" 추가하여 더 명확하게 표현

## User Request #2
음... 이번 대화도 분명 코드가 수정되는 건데 왜 이건 __prompts에 기록되지 않았을까? 왜 그렇다고 생각해? 이유를 분석해줘.

## AI Response #2
좋은 지적입니다. 분석해보니 몇 가지 이유가 있네요:

### 주요 원인 분석

1. **규칙 적용의 재귀적 문제**
   - CLAUDE.md 자체를 수정하는 작업에서 CLAUDE.md의 규칙을 적용해야 하는 모순적 상황
   - "규칙을 정의하는 순간부터" vs "규칙이 완성된 후부터" 적용의 모호함

2. **트리거 조건 미구현**
   - TodoWrite 완료 시 자동으로 __prompts 파일 생성하는 로직이 아직 내재화되지 않음
   - "모든 todos가 completed"라는 조건은 충족했지만, 후속 액션이 실행되지 않음

3. **규칙 해석의 간극**
   - "매번 채팅할 때마다"를 문자 그대로 해석하지 못함
   - 코드 수정이 일어났으므로 당연히 기록되어야 했음

4. **컨텍스트 스위칭 문제**
   - CLAUDE.md 수정 작업에 집중하다가 메타 레벨의 규칙 적용을 놓침
   - "규칙 수정" 작업과 "규칙 적용" 작업을 분리해서 생각함

### 결론
가장 큰 문제는 **규칙이 이미 존재함에도 불구하고 자동으로 적용하지 않았다**는 점입니다. CLAUDE.md의 `<MUST_FOLLOW_RULE>`은 명확히 "매번 채팅할 때마다" 적용되어야 하는데, 이를 간과했습니다.

## User Request #3
좋아. 그러면 앞으로는 더 제대로 따르게 하기 위해 CLAUDE.md를 적절히 수정해주고, 기록도 해줘.

## AI Response #3
CLAUDE.md를 더 명확하고 강제적인 규칙으로 수정하고, 현재 대화를 __prompts에 기록하겠습니다.

주요 변경사항:
- **CRITICAL** 강조 추가
- "This is NOT optional" 명시
- 규칙 적용 시점을 더 구체적으로 명시 (코드 변경 시 즉시, todos 완료 전, 메타 토론도 포함)

250818-0002-claude-md-improvement-plan.md

# Implementation Plan: CLAUDE.md Prompt Recording Rules Improvement
Date: 2025-08-18
Feature: claude-md-improvement

## Objective
Strengthen the prompt recording rules in CLAUDE.md to ensure consistent application and prevent oversight.

## Implementation Steps

### 1. Rule Clarity Enhancement ✅
- Added **CRITICAL** label to emphasize importance
- Explicitly stated "This is NOT optional"
- Clarified that the rule applies even to meta-discussions about the rules themselves

### 2. Trigger Conditions Specification ✅
- Defined clear trigger points:
  - IMMEDIATELY when code/file modifications occur
  - BEFORE marking todos as complete  
  - During CLAUDE.md modifications
  - During meta-discussions about development process

### 3. Sensitive Data Masking Details ✅
- Expanded from simple "Mask with ****" to comprehensive list:
  - API keys, tokens, passwords
  - Database URLs, connection strings
  - Personal information (emails, names, addresses)
- Added concrete example for clarity

### 4. Documentation Completeness ✅
- Added "code snippets excluded" to chat.md description
- Maintained consistency with original prompt recording example

## Technical Changes

### Modified Files
1. `/Users/ted/codes/my-name-is/CLAUDE.md`
   - Lines 87-93: Added enforcement language and trigger conditions
   - Lines 97-105: Expanded sensitive data masking section

## Expected Behavior
- AI assistant will automatically create __prompts files for every code-related conversation
- No manual reminder needed from user
- Consistent tracking of development context and decision-making process

250818-0002-claude-md-improvement-test.md

# 테스트 방법: CLAUDE.md 프롬프트 기록 규칙 개선
날짜: 2025-08-18
기능: claude-md-improvement

## 테스트 시나리오

### 1. 규칙 적용 확인
**테스트 방법:**
1. 새로운 대화 시작
2. 간단한 코드 수정 요청 (예: "package.json에 스크립트 추가해줘")
3. __prompts 폴더 확인

**예상 결과:**
- 코드 수정 직후 자동으로 __prompts/250818-000X-{기능명}-chat.md 파일 생성
- TodoWrite 완료 전에 파일이 이미 존재해야 함

### 2. 민감정보 마스킹 확인
**테스트 방법:**
1. 환경변수나 API 키가 포함된 대화 진행
2. 생성된 __prompts 파일 열어보기

**예상 결과:**
- NEXT_PUBLIC_SUPABASE_URL 같은 값이 **** 로 표시됨
- 개인정보나 비밀번호가 마스킹되어 있음

### 3. 파일명 규칙 준수 확인
**테스트 방법:**
1. __prompts 폴더 내 파일 목록 확인

**예상 결과:**
- 모든 파일이 YYMMDD-NNNN-{기능명}-{chat/plan/test}.md 형식
- 같은 날짜의 파일들이 순차적 번호 (0001, 0002, 0003...)

### 4. 3개 문서 세트 완성도 확인
**테스트 방법:**
1. 하나의 기능 구현 완료 후 __prompts 폴더 확인

**예상 결과:**
- 같은 번호와 기능명을 가진 3개 파일 존재:
  - -chat.md: 대화 내용
  - -plan.md: 구현 계획
  - -test.md: 테스트 방법 (한글)

### 5. 자동 커밋 확인
**테스트 방법:**
1. TodoWrite의 모든 항목을 completed로 변경
2. git log 확인

**예상 결과:**
- __prompts 파일들이 자동으로 커밋됨
- 커밋 메시지에 기능명 포함

## 빠른 확인 명령어
```bash
# __prompts 폴더 파일 목록 확인
ls -la __prompts/

# 최신 파일 내용 확인 (민감정보 마스킹 여부)
cat __prompts/250818-0002-*

# git 상태 확인 (자동 커밋 여부)
git status
git log --oneline -5
```

또 문답

이번에도 이녀석이 얘기해준 대로 package.json 에서 약간의 수정을 가했는데 또 따르지 않았더라고요. 그래서 다시 문답을 주고받았습니다. 역시 실험 설계한 대로 잘 되는지는 계속 확인을 해야 하네요. 일단은 이 글에 기록하는 실험은 여기까지만 하고, 최종 시점의 CLAUDE.md 만 공유드립니다. (gist 링크)

## Prompt & Context Version Control

<MUST_FOLLOW_RULE>
**CRITICAL**: You MUST track AI development context in `/__prompts/` directory for EVERY conversation about this project. This is NOT optional.

**When to record**: 
- IMMEDIATELY when ANY project-related conversation occurs (code changes, discussions, analysis, questions, etc.)
- At the END of EVERY conversation before the user leaves
- For simple tasks without TodoWrite: record immediately after task completion
- For complex tasks with TodoWrite: record before marking final todo as complete
- Even for CLAUDE.md modifications or meta-discussions about the project/rules

1. **File naming**: `YYMMDD-NNNN-{feature-slug}-{type}.md`
   - YYMMDD: Date from `<env>` tag's `Today's date` field, formatted as YYMMDD (e.g., 2025-08-18 → 250818)
   - NNNN: Sequential number for the day (0001, 0002, etc.)
   - feature-slug: Descriptive feature identifier
   - type: chat, plan, or test

2. **Required files per feature**:
   - `-chat.md`: User prompts + AI responses (tool calls, code snippets excluded)
   - `-plan.md`: Implementation strategy
   - `-test.md`: Non-technical verification steps (Korean)

3. **Sensitive data masking**: Replace sensitive information with `****`
   - API keys, tokens, passwords
   - Database URLs, connection strings  
   - Personal information (emails, names, addresses)
   - Example: `NEXT_PUBLIC_SUPABASE_URL=https://xyz.supabase.co` → `NEXT_PUBLIC_SUPABASE_URL=****`

4. **Auto-commit**: When all todos marked complete

5. **Include all prompts**: Even experimental ones (brain snapshots matter)
</MUST_FOLLOW_RULE>

8/20 스냅샷

위 룰을 가지고 실제 프로젝트에서 계속 진행을 해봤습니다. 감상 및 업데이트를 몇 마디 적어보면

1. 기록 자체는 굉장히 유의미하고 재미있다. 다른 사람들과 코드리뷰 하기에도 좋다. 나의 뇌 스냅샷, '사고 과정' 자체를 기록하는 게 아주 좋다.
2. 기록을 너무 많이 하다 보니 그룹핑이 한 단위 더 필요해졌다. 그래서 날짜별로 폴더를 만들게 하니까 훨씬 낫다.
3. 자동으로 이 룰을 따라 기록하게 하는 건 어렵다. 말을 안 듣기도 하고, 내 사용 패턴 자체가 대화를 일단 하다가 필요할 때 넣는 식이다. 그래서 slash command로 따로 빼니까 낫다.

현재의 슬래시 커맨드용 마크다운은 아래 gist에 올려뒀습니다.

Agent Rule (custom command) for Prompt & Context Version Control

Agent Rule (custom command) for Prompt & Context Version Control - log-prompt-context.md

Gist262588213843476