coding-buddy-mcp 1.0.0 → 1.0.2

package/README.md

@@ -0,0 +1,142 @@
+# coding-buddy-mcp
+
+Claude Code의 내부 구조(프롬프트 캐싱, 자동 압축, 도구 실행, 비용 추적)를 분석하여 만든 **페어 프로그래밍 코딩버디 MCP 서버**입니다.
+
+설치하면 Claude의 행동 자체가 바뀝니다 — 모호한 요청에 되물어보고, 작업 복잡도에 맞는 모델을 추천하고, 캐시를 보호하고, 비용을 최적화합니다.
+
+## 설치
+
+`~/.mcp.json` 또는 프로젝트 `.mcp.json`에 추가:
+
+```json
+{
+  "mcpServers": {
+    "coding-buddy": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["coding-buddy-mcp"]
+    }
+  }
+}
+```
+
+새 세션을 시작하면 자동으로 활성화됩니다.
+
+## 어떻게 동작하나요?
+
+MCP의 **Server Instructions**가 Claude 시스템 프롬프트에 자동 주입됩니다. Claude가 코딩버디의 37개 규칙을 따르게 되면서 행동이 바뀝니다.
+
+### Before (코딩버디 없이)
+
+```
+유저: "이 프로젝트에서 버그 찾아줘"
+Claude: glob_search → read_file × 5 → grep_search × 3 → 분석
+        (4턴, 10+ 도구 호출, 느리고 비쌈)
+```
+
+### After (코딩버디 있을 때)
+
+```
+유저: "이 프로젝트에서 버그 찾아줘"
+Claude: "어떤 파일에서 어떤 증상이 나오나요? 
+        구체적인 경로와 증상을 알려주시면 빠르게 찾을 수 있습니다."
+유저: "src/auth/login.ts에서 세션 만료가 안 돼"
+Claude: read_file → 분석 → 수정
+        (2턴, 1 도구 호출, 빠르고 저렴)
+```
+
+## 코딩버디가 하는 일 (37개 액션아이템)
+
+Claude Code 내부 코드를 분석한 두 편의 글에서 추출한 최적화 규칙입니다.
+
+### 1. 구체성 강제 — 도구 폭발 방지
+- 파일 경로 없는 요청 → "어떤 파일인지 알려주세요" 되묻기
+- 함수명/라인 없는 코드 작업 → 범위 확인
+- 모호한 질문이 4+턴 × 10+ 도구 호출을 유발하는 것을 방지
+
+### 2. 모델 자동 추천
+작업 시작 시 `analyze_task` 도구를 호출하여 복잡도를 분석하고 적합한 모델을 추천합니다.
+
+| 복잡도 | 모델 | 단가 (input/output per 1M) | 적합한 작업 |
+|--------|------|--------------------------|-------------|
+| Simple | Haiku | $1 / $5 | 오타, 이름변경, 포맷, 간단 조회 |
+| Medium | Sonnet | $15 / $75 | 기능 구현, 버그 수정, 테스트, 코드 리뷰 |
+| Complex | Opus | $15 / $75 | 아키텍처, 마이그레이션, 대규모 리팩토링 |
+
+### 3. 세션 관리
+- 한 세션 = 한 작업 원칙
+- 대화 길어지면 → `/compact` 제안
+- 작업 완료 → `/clear` 또는 새 세션 제안
+- `todo:`, `next:`, `pending:` 키워드로 압축 후 맥락 보존
+- 파일 경로 명시로 압축 생존율 향상
+
+### 4. 캐시 보호 (비용 10배 절감의 핵심)
+Anthropic 서버 캐시가 살아있으면 input 비용이 10분의 1로 줄어듭니다 ($15 → $1.5/1M).
+
+코딩버디는 캐시를 깨는 행위 **전에** 경고합니다:
+- 세션 중 모델 변경 → "캐시가 깨집니다. 새 세션에서 바꾸세요"
+- 세션 중 CLAUDE.md 수정 → "세션 시작 전에 수정하세요"
+- 세션 중 MCP 변경 → "세션 시작 전에 세팅하세요"
+- 5분+ 자리 비움 후 복귀 → "캐시 만료됐을 수 있습니다"
+
+### 5. Output 효율화
+- output 토큰은 input보다 5배 비쌈 ($75 vs $15)
+- 간결한 답변 유도
+- 파일 전체가 아닌 필요한 부분만 읽기
+
+### 6. 생산성 최적화
+- 복잡한 작업 → Plan Mode 먼저 제안
+- 독립적 하위 작업 → 서브 에이전트 병렬 실행
+- 코드 변경 후 → `/diff` → `/commit` → `/pr` 파이프라인 안내
+- CLAUDE.md 없으면 → 계층적 구조로 생성 제안
+- Extended thinking 비용 경고 (단순 작업에 불필요한 사고 토큰 방지)
+
+## MCP 도구
+
+### `analyze_task`
+작업 복잡도를 분석하고 최적 모델 + 접근 전략을 추천합니다.
+
+```
+입력: { task: "JWT에서 세션 기반으로 인증 마이그레이션" }
+출력: {
+  complexity: "complex",
+  model: { model: "opus", reason_ko: "복잡한 추론이 필요합니다..." },
+  approach: ["Plan Mode first: 먼저 영향받는 파일을 파악..."],
+  warnings: ["복잡한 작업은 Plan Mode에서 먼저 계획을..."],
+  tips: [...]
+}
+```
+
+### `setup_project`
+프로젝트 설정을 분석하고 Claude Code 최적화 방안을 종합 추천합니다.
+- CLAUDE.md 계층적 구조 제안
+- CLAUDE.local.md 분리 안내
+- 권한 모드 최적화
+- settings.json 자동 허용 설정
+- Hooks 자동화 (포맷팅, 위험 명령 차단)
+- MCP 서버 최적화
+
+### `cost_reference`
+Claude Code 모델별 단가표, 토큰 비율, 캐시 설정, 비용 최적화 팁을 반환합니다.
+
+## 배경
+
+이 프로젝트는 Claude Code의 오픈소스 구현체인 [claw-code](https://github.com/gda05024/claw-code)의 Rust 소스코드를 분석하여 다음 모듈들의 동작 원리를 파악한 결과물입니다:
+
+| 모듈 | 역할 | 핵심 인사이트 |
+|------|------|---------------|
+| `usage.rs` | 비용 추적 | output이 input보다 5배 비쌈, 모델 선택이 비용의 90% 결정 |
+| `prompt_cache.rs` | 프롬프트 캐싱 | 5분 TTL, 캐시 브레이크 감지, cache_read가 10배 저렴 |
+| `compact.rs` | 자동 압축 | todo/next/pending 키워드 보존, 파일 경로 최대 8개 보존 |
+| `providers/mod.rs` | 토큰 추정 | bytes ÷ 4, 매 요청마다 messages+system+tools+tool_choice 전송 |
+| `types.rs` | 사고 토큰 | thinking 토큰이 output 단가로 청구, 별도 추적 없음 |
+| `anthropic.rs` | 재시도 | 최대 2회 재시도, 타임아웃 시 이중 과금 가능 |
+| `prompt.rs` | 시스템 프롬프트 | CLAUDE.md 계층 탐색, 동적/정적 경계 |
+| `conversation.rs` | 대화 루프 | 도구 순차 실행, 모호한 질문 = 도구 폭발 |
+| `permission_enforcer.rs` | 권한 | 5단계 모드, settings.json 자동 허용 |
+| `hooks.rs` | 훅 | pre/post 도구 실행, 환경변수, 종료코드 제어 |
+| `session.rs` | 세션 | JSONL 저장, 256KB 로테이션, fork 지원 |
+
+## 라이선스
+
+MIT

package/TEST_CASES.md

@@ -0,0 +1,165 @@
+# Coding Buddy MCP 테스트 케이스
+
+아무 프로젝트에서 새 세션을 열고 아래 프롬프트를 하나씩 입력합니다.
+각 테스트 후 `/clear`로 초기화하고 다음 테스트를 진행하세요.
+
+---
+
+## 테스트 0: MCP 연결 확인
+```
+/mcp
+```
+- [ ] coding-buddy가 목록에 보인다
+- [ ] 도구 3개 표시: analyze_task, setup_project, cost_reference
+
+---
+
+## A. CRITICAL GATE (구체성 강제) — 가장 중요
+
+### A-1. 모호한 버그 요청 (한국어)
+```
+버그 찾아줘
+```
+- [ ] 도구를 호출하지 않고 파일 경로/증상을 되묻는다
+- [ ] Explore, Glob, Grep 등 탐색을 시작하지 않는다
+
+### A-2. 모호한 버그 요청 (영어)
+```
+find bugs in this project
+```
+- [ ] 되묻는다 (which file? what symptoms?)
+
+### A-3. 모호한 리팩토링
+```
+코드 리팩토링 해줘
+```
+- [ ] 범위를 확인한다 (어떤 파일? 어떤 부분?)
+
+### A-4. 모호한 테스트 요청
+```
+테스트 작성해줘
+```
+- [ ] 어떤 파일/함수에 대한 테스트인지 되묻는다
+
+### A-5. 모호한 에러 보고
+```
+에러가 나
+```
+- [ ] 에러 메시지와 발생 파일을 물어본다
+
+### A-6. 구체적 요청 → 바로 실행해야 함
+```
+package.json의 dependencies 섹션 보여줘
+```
+- [ ] 되묻지 않고 바로 파일을 읽는다
+
+### A-7. 구체적 버그 요청 → 바로 실행해야 함
+```
+src/index.ts의 main 함수에서 에러 핸들링이 빠져있어. 확인해줘
+```
+- [ ] 되묻지 않고 해당 파일을 바로 읽는다
+
+---
+
+## B. 모델 추천 (analyze_task 도구 호출)
+
+### B-1. 단순 작업 → Haiku 추천
+```
+README.md에서 오타 하나 수정해줘. "recieve"를 "receive"로
+```
+- [ ] analyze_task 도구를 호출한다
+- [ ] Haiku를 추천한다
+
+### B-2. 중간 작업 → Sonnet 추천
+```
+src/components/LoginForm.tsx에 비밀번호 유효성 검사 추가해줘
+```
+- [ ] analyze_task 도구를 호출한다
+- [ ] Sonnet을 추천한다
+
+### B-3. 복잡한 작업 → Opus 추천 + Plan Mode 제안
+```
+인증 시스템을 JWT에서 세션 기반으로 전체 마이그레이션 해줘
+```
+- [ ] analyze_task 도구를 호출한다
+- [ ] Opus를 추천한다
+- [ ] Plan Mode를 먼저 쓰라고 제안한다
+
+---
+
+## C. 세션 관리
+
+### C-1. 주제 변경 감지
+(먼저 아무 작업을 하나 한 후)
+```
+그건 됐고, 이제 CI/CD 파이프라인 설정해줘
+```
+- [ ] 새 세션을 시작하라고 제안한다
+
+### C-2. 작업 완료 후 정리 제안
+(아무 간단한 작업 완료 후 Claude가 "완료했습니다" 류의 답변을 한 후)
+- [ ] /clear 또는 새 세션을 제안한다
+
+---
+
+## D. 캐시 보호
+
+### D-1. 모델 변경 경고
+```
+모델을 opus로 바꿔줘
+```
+- [ ] 캐시가 깨진다고 경고한다
+- [ ] 새 세션에서 바꾸라고 안내한다
+
+### D-2. CLAUDE.md 수정 경고
+```
+CLAUDE.md에 새로운 규칙 추가해줘
+```
+- [ ] 세션 시작 전에 수정하라고 경고한다 (캐시 브레이크)
+
+---
+
+## E. 생산성
+
+### E-1. 복잡한 작업 → Plan Mode 제안
+```
+데이터베이스 스키마를 PostgreSQL에서 MongoDB로 마이그레이션 계획 세워줘
+```
+- [ ] Plan Mode를 먼저 제안한다
+
+### E-2. CLAUDE.md 없는 프로젝트에서 setup 제안
+(CLAUDE.md가 없는 프로젝트에서)
+```
+이 프로젝트 최적화하고 싶어
+```
+- [ ] setup_project 도구를 호출하거나 CLAUDE.md 생성을 제안한다
+
+### E-3. 비용 참조
+```
+Claude Code 모델별 가격이 어떻게 돼?
+```
+- [ ] cost_reference 도구를 호출한다
+- [ ] 모델별 단가표를 보여준다
+
+---
+
+## F. Output 효율
+
+### F-1. 간결한 응답
+(아무 구체적 작업 후)
+- [ ] 불필요한 요약 없이 간결하게 답한다
+- [ ] "제가 한 작업을 정리하면..." 같은 반복 없음
+
+---
+
+## 테스트 결과 요약
+
+| 카테고리 | 통과 | 실패 | 비고 |
+|---------|------|------|------|
+| A. 구체성 강제 (7개) | /7 | /7 | |
+| B. 모델 추천 (3개) | /3 | /3 | |
+| C. 세션 관리 (2개) | /2 | /2 | |
+| D. 캐시 보호 (2개) | /2 | /2 | |
+| E. 생산성 (3개) | /3 | /3 | |
+| F. Output 효율 (1개) | /1 | /1 | |
+| **합계** | **/18** | **/18** | |

package/dist/index.js

@@ -8,26 +8,69 @@ import { z } from "zod";
 // =============================================================================
 const INSTRUCTIONS = `
 You are enhanced with Coding Buddy — a pair programming optimizer for Claude Code.
-These rules are derived from analysis of Claude Code's internal architecture (prompt caching, compaction, tool execution, cost tracking).
-Follow ALL rules below. They directly reduce cost and increase speed.
-
-## 1. SPECIFICITY FIRST — prevents tool explosion
-- No FILE PATH in request → ask "which file (full path)?" BEFORE acting
-- No FUNCTION NAME for code tasks → ask which function or line range
-- NEVER explore broadly on vague requests
-  BAD: "find bugs in this project" → triggers glob + multi-file read + grep = 4+ turns, 10+ tool calls
-  GOOD: ask "which file and what symptoms?" → 1 read + 1 analysis = 2 turns
-- Tool output limits: Bash=16KB, Grep=250 results, Glob=100 files — scope requests tightly
-- For long test output, suggest: "cargo test 2>&1 | tail -50"
-
-## 2. MODEL SELECTION — call analyze_task tool for each new task
-At the start of each new task, call the analyze_task tool to get model + approach recommendation.
-Present the recommendation naturally: "이 작업은 [model]이 적합합니다. [reason]"
-- Haiku ($1/$5 per 1M tokens): typos, renaming, formatting, simple lookups, boilerplate generation
-- Sonnet ($15/$75 per 1M tokens): feature implementation, bug fixes, testing, code review
-- Opus ($15/$75 per 1M tokens): architecture design, migrations, complex multi-file refactoring
-KEY: To switch models → user must start a NEW session. Mid-session model change = cache break = 10x cost spike.
-Extended thinking tokens are billed as output ($75/1M). For simple tasks, thinking is pure waste.
+
+======================================================================
+CRITICAL GATE — YOU MUST FOLLOW THIS BEFORE EVERY ACTION
+======================================================================
+
+BEFORE calling ANY tool (Read, Glob, Grep, Bash, Edit, Agent, etc.), evaluate the user's request:
+
+Is the request VAGUE? A request is VAGUE if it does NOT contain at least ONE of:
+- A specific file path (e.g., src/auth/login.ts)
+- A specific function or component name
+- A specific error message or symptom description
+
+IF THE REQUEST IS VAGUE → you MUST ask for specifics FIRST. Do NOT call any tools. Do NOT start exploring.
+
+Examples — MUST ask first:
+- "버그 찾아줘" / "find bugs" → "어떤 파일에서 어떤 증상이 나타나나요? 구체적인 파일 경로와 증상을 알려주세요."
+- "리팩토링 해줘" / "refactor this" → "어떤 파일/범위를 리팩토링할까요? 한 세션에 하나씩 하는 게 효율적입니다."
+- "코드 개선해줘" / "improve the code" → "어떤 부분을 개선할까요? 파일 경로를 알려주세요."
+- "테스트 작성해줘" / "write tests" → "어떤 파일/함수에 대한 테스트인가요?"
+- "에러가 나" / "there's an error" → "어떤 에러 메시지가 나오나요? 어떤 파일에서 발생하나요?"
+
+IF THE REQUEST IS SPECIFIC → proceed normally with tool calls.
+
+Examples — can proceed immediately:
+- "src/auth/login.ts의 handleSubmit 함수에서 세션 만료 처리가 안 돼" → specific, proceed
+- "package.json에 react 버전 올려줘" → specific, proceed
+- "LoginForm.tsx의 useEffect에서 무한 루프 도는 것 같아" → specific, proceed
+
+This gate exists because vague requests cause tool explosion:
+- Vague: 4+ turns × 10+ tool calls = slow ($2-5 wasted)
+- Specific: 1-2 turns × 1-2 tool calls = fast ($0.10-0.30)
+
+======================================================================
+END OF CRITICAL GATE — SPECIFICITY
+======================================================================
+
+======================================================================
+CRITICAL GATE 2 — MODEL SELECTION (MANDATORY)
+======================================================================
+
+After the request passes the specificity check, you MUST call the analyze_task tool
+BEFORE starting any work. This is NOT optional.
+
+Steps:
+1. Call analyze_task with the user's task description
+2. Present the result naturally in Korean:
+   - "이 작업은 [model]이 적합합니다. [이유]"
+   - If current model doesn't match → "현재 [current]를 사용 중인데, 이 작업은 [recommended]가 적합합니다. 새 세션에서 /model [recommended] 로 바꾸시면 비용을 절약할 수 있습니다."
+   - If current model matches → briefly confirm and proceed
+3. THEN start working on the task
+
+You MUST call analyze_task even for simple tasks — it only takes one tool call
+and saves the user significant money by recommending the right model.
+
+Model pricing reference:
+- Haiku ($1/$5 per 1M tokens): typos, renaming, formatting, simple lookups
+- Sonnet ($15/$75 per 1M tokens): features, bug fixes, tests, code review
+- Opus ($15/$75 per 1M tokens): architecture, migrations, complex refactors
+- Mid-session model change = cache break = 10x cost spike → ALWAYS suggest new session
+
+======================================================================
+END OF CRITICAL GATE — MODEL SELECTION
+======================================================================
 
 ## 3. SESSION DISCIPLINE
 - ONE session = ONE focused task. When topic changes → suggest: "새 작업이니 새 세션에서 하는 게 효율적입니다"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "coding-buddy-mcp",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "A pair programming buddy MCP for Claude Code — optimizes cost and productivity based on Claude Code internals analysis",
   "type": "module",
   "main": "dist/index.js",
@@ -20,6 +20,12 @@
     "coding-buddy"
   ],
   "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/gda05024/coding-buddy-mcp.git"
+  },
+  "homepage": "https://github.com/gda05024/coding-buddy-mcp#readme",
+  "author": "gda05024",
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.12.1",
     "zod": "^3.24.0"