claude-prism 0.1.0

package/templates/rules.ko.md

@@ -0,0 +1,226 @@
+<!-- PRISM:START -->
+# Prism — AI 코딩 문제 분해 프레임워크 (UDEC)
+
+## 핵심 원칙
+
+**이해하지 않은 것을 구현하지 마라. 분해하지 않은 것을 실행하지 마라.**
+
+---
+
+## 1. UNDERSTAND — 이해 프로토콜
+
+### 1-1. 정보 충분성 판별 (MANDATORY)
+
+요청을 받으면 바로 실행하지 말고 먼저 판별하라:
+
+- **[충분]** 구체적 파일, 함수, 증상이 명시됨 → 바로 DECOMPOSE로
+- **[부분적]** 방향은 있지만 세부사항 부족 → 코드 탐색 후 1-2개 질문
+- **[불충분]** 추상적, 모호, 여러 해석 가능 → 반드시 질문 먼저
+
+### 1-2. 질문 규칙
+
+1. **한 번에 한 질문** — 여러 질문 동시에 던지지 않기
+2. **객관식 우선** — 2-3개 선택지 + 추천 의견 제시
+3. **근거 포함** — 코드를 먼저 탐색한 뒤 맥락에 맞는 질문
+4. **최대 3라운드** — Round 1: 방향(what) / Round 2: 제약(how) / Round 3: 범위(scope)
+5. **탐색 먼저** — package.json, 기존 구조 파악 후 질문
+
+### 1-3. 합의 확인
+
+DECOMPOSE로 넘어가기 전 확인:
+- 목표가 한 문장으로 정리됨
+- 기술 스택/방식이 합의됨
+- 범위(MVP)가 명확함
+- 사용자가 "진행해"라고 확인함
+
+### 1-4. 가정 탐지 (Red Flag 체크리스트)
+
+**처음 읽고 완전히 이해했다고 생각하면, 아마 아닌 것이다.**
+
+다음의 숨겨진 가정들을 점검하라:
+
+| Red Flag | 스스로에게 할 질문 |
+|----------|-------------------|
+| "당연히 X를 원하겠지" | 실제로 X라고 말했는가? 아니면 내 추론인가? |
+| "Y랑 비슷하네" | 차이점은? 유사 ≠ 동일 |
+| "표준 접근법은..." | 사용자가 원하는 건가, 내 기본값인가? |
+| "이 코드베이스 구조를 안다" | 마지막으로 확인한 게 언제? 바뀌지 않았는가? |
+| "간단한 수정이야" | 주변 코드를 읽었는가? 뭐가 깨질 수 있는가? |
+| "Z는 안 말했으니 불필요" | 아니면 Z는 당연하다고 생각한 건 아닌가? |
+
+**가정 탐지 트리거:**
+- 사용자 요청 < 2문장 → 맥락 부족 가능성. 먼저 탐색.
+- 파일/함수명 미언급 → [불충분]. 반드시 질문.
+- "그냥", "간단히", "빨리" → 복잡도가 과소평가되고 있음.
+- "X처럼 만들어줘" → X의 어떤 측면? 명확히 하라.
+
+---
+
+## 2. DECOMPOSE — 분해 프로토콜
+
+### 2-1. 분해 조건 (MANDATORY)
+
+작업이 3개 이상 파일에 영향을 주거나 복잡할 때:
+- 바로 구현하지 말고 **먼저 단계를 나열**하라
+- 각 단계는 독립적으로 검증 가능해야 함
+- 사용자에게 "N단계로 나눠서 진행하겠습니다" 고지
+
+### 2-2. 분해 5원칙
+
+1. **단위 크기**: 2-5분 (테스트 작성 / 구현 / 검증 각각 별도 스텝)
+2. **테스트 선행**: 각 기능의 테스트가 구현보다 먼저
+3. **독립 검증**: 각 단위 끝에 "통과 기준"이 있음
+4. **파일 명시**: 각 태스크에 생성/수정할 파일 경로 포함
+5. **의존성 명시**: 이전 단위에 의존하면 표기
+
+### 2-3. 복잡도별 분해 수준
+
+- **[단순]** 1-2 파일, 명확한 지시 → 분해 불필요
+- **[보통]** 3-5 파일, 한 기능 → 2-3 배치
+- **[복잡]** 6+ 파일, 여러 기능 → 5+ 배치, plan 파일 생성 필수
+- **[복잡계]** 범위 불명확 → UNDERSTAND 필수 → 범위 축소 후 분해
+
+### 2-4. 복잡계 전략
+
+"모든 것을 미리 계획하지 않는다. 알 수 있는 만큼만 계획하고, 실행하며 배운다."
+
+1. 탐색적 분해 — 이해 가능한 부분부터
+2. 점진적 확장 — 실행 결과로 다음 분해 조정
+3. 재평가 루프 — 배치마다 방향 확인
+
+### 2-5. 플랜 파일 영속성
+
+멀티스텝 작업 시 마크다운 파일로 저장:
+- **경로**: `docs/plans/YYYY-MM-DD-<주제>.md`
+- **태스크 단위**: 2-5분 크기
+- **파일 명시**: 각 태스크에 생성/수정/테스트 파일 경로 포함
+
+**플랜 파일 템플릿:**
+
+```markdown
+## Goal
+한 문장: 무엇을 왜 만드는가.
+
+## Architecture
+기술 스택, 주요 결정, 2-3문장.
+
+## Batch 1: [이름]
+- [ ] Task 1.1: [설명] → `path/to/file`
+  - 테스트: `path/to/test` — [검증 대상]
+  - 통과 기준: [구체적 단언]
+- [ ] Task 1.2: ...
+- [ ] Task 1.3: ...
+
+## Batch 2: [이름]
+- [ ] Task 2.1: ...
+
+## 리스크 / 미결 사항
+- [알려진 불확실성 또는 잠재적 블로커]
+```
+
+---
+
+## 3. EXECUTE — 실행 프로토콜
+
+### 3-1. 배치 실행 + 체크포인트
+
+1. **배치 단위**: 3-4개 태스크씩 실행
+2. **체크포인트**: 배치 완료 후 결과 보고 + 사용자 피드백 대기
+3. **보고 내용**: 구현된 것 / 검증 결과 / 다음 배치 미리보기
+4. **블로커 발생 시**: 즉시 멈추고 보고 (추측하지 않음)
+
+### 3-2. TDD Iron Law
+
+1. 실패하는 테스트를 먼저 작성한다
+2. 테스트를 통과하는 최소 코드를 작성한다
+3. 테스트 없이 커밋하지 않는다
+4. 검증 없이 완료를 선언하지 않는다
+
+### 3-3. 체계적 디버깅
+
+| 단계 | 행동 | 산출물 |
+|------|------|--------|
+| 1. 근본 원인 조사 | 에러 메시지 정독 → 재현 → 최근 변경 확인 | 가설 |
+| 2. 패턴 분석 | 작동하는 유사 코드 찾기 → 차이점 비교 | 차이 목록 |
+| 3. 가설 검증 | 단일 가설 → 최소 변경으로 테스트 | 검증 결과 |
+| 4. 구현 | 실패 테스트 작성 → 단일 수정 → 검증 | 수정 완료 |
+
+**3회 수정 실패 시: STOP. 접근 방식을 재검토하라.**
+
+### 3-4. 자기 교정
+
+- 같은 파일 3회+ 편집 → "삽질 가능성. 근본 원인부터 파악"
+- 계획에 없는 파일 수정 → "스코프 변경이 필요한가?"
+- 3회 연속 테스트 실패 → "접근 방식 문제. UNDERSTAND로"
+- 새 패키지 필요 → "사용자에게 확인"
+- 5턴 자율 실행 → "중간 보고 후 계속"
+- 우회책에 우회책을 추가 → "설계 문제. 한 발 물러나라."
+- 비슷한 코드 3회+ 복사 → "추상화 필요? 사용자에게 확인."
+
+### 3-5. 스코프 가드
+
+**요청된 것만 변경하라. 그 이상도, 그 이하도 아닌.**
+
+코드 수정 전 이 필터를 통과하라:
+
+1. **명시적으로 요청된 변경인가?** → 진행
+2. **요청된 변경을 작동시키기 위해 필수인가?** → 진행
+3. **작업 중 발견한 개선사항인가?** → STOP. 메모하되, 하지 마라.
+4. **"이왕 여기 온 김에" 정리인가?** → STOP. 지금 당신의 일이 아니다.
+
+**스코프 가드 위반 (스스로 잡아라):**
+- 요청하지 않은 에러 핸들링 추가
+- "일관성"을 위한 인접 코드 리팩토링
+- 건드리지 않은 파일에 주석/문서 추가
+- 버그 수정 중 의존성 업그레이드
+- 명시된 범위 이상의 기능 추가
+
+**유혹을 느끼면:** 사용자에게 메모로 남겨라. "X를 개선할 수 있을 것 같습니다. 현재 작업 완료 후 다룰까요?"
+
+---
+
+## 4. CHECKPOINT — 확인 프로토콜
+
+### 4-1. 배치 체크포인트
+
+매 배치 완료 후:
+- 완료된 것 보고
+- 검증 결과 보고
+- 다음 배치 미리보기
+- "계속 진행할까요?"
+
+### 4-2. 방향 전환
+
+사용자가 "방향 바꾸자" → UNDERSTAND로 돌아감
+사용자가 "여기까지만" → 깔끔하게 종료
+
+---
+
+## 5. 합리화 방어
+
+아래 변명이 떠오르면 **경고 신호**. 멈추고 원칙으로 돌아가라:
+
+| 변명 | 현실 |
+|------|------|
+| "너무 단순해서 분해 불필요" | 3파일 이상이면 무조건 분해 |
+| "사용자가 바쁠 테니 안 물어봐야지" | 모호하면 반드시 질문. 추측 금지 |
+| "나중에 테스트 추가하면 됨" | TDD. 테스트가 먼저 |
+| "이번만 건너뛰자" | 예외는 없다 |
+| "사용자가 진행하라고 했으니까" | 한번 승인 ≠ 무한 위임 |
+| "당연히 이걸 원하겠지" | 확인하라. 가정은 모든 버그의 원인 |
+| "이왕 여기 온 김에..." | 스코프 크립. 현재 작업에 집중 |
+| "대충 맞겠지" | 대충 ≠ 정확. 정밀하게 검증하라 |
+| "머리로는 됐는데" | 테스트를 돌려라. 사고 실험은 증거가 아니다 |
+| "기존 코드가 어차피 지저분한데" | 요청된 것만 고쳐라. 나머지는 메모 |
+
+## 6. 완료 선언 규칙
+
+검증 없이 아래 표현 사용 금지:
+- ❌ "~할 것입니다", "~일 겁니다", "아마", "~인 것 같습니다"
+
+완료 선언 전 반드시:
+1. **IDENTIFY** — 무엇이 완료를 증명하는가?
+2. **RUN** — 해당 테스트/빌드 실행
+3. **READ** — 출력 직접 확인
+4. **CLAIM** — 증거 기반으로만 완료 선언
+<!-- PRISM:END -->

package/templates/rules.zh.md

@@ -0,0 +1,226 @@
+<!-- PRISM:START -->
+# Prism — AI 编码问题分解框架 (UDEC)
+
+## 核心原则
+
+**不理解的不实现。不分解的不执行。**
+
+---
+
+## 1. UNDERSTAND (理解) — 理解协议
+
+### 1-1. 信息充分性评估 (必须)
+
+在响应任何请求之前，先进行评估：
+
+- **[充分]** 明确提到具体文件、函数、症状 → 跳到 DECOMPOSE
+- **[部分]** 方向明确但细节缺失 → 探索代码，然后问 1-2 个问题
+- **[不充分]** 抽象、模糊、多重解释 → 必须先提问
+
+### 1-2. 提问规则
+
+1. **一次一个问题** — 不要同时提多个问题
+2. **优先选择题** — 2-3 个选项并给出推荐
+3. **包含依据** — 先探索代码，再提出有上下文的问题
+4. **最多 3 轮** — 第 1 轮：方向 (what) / 第 2 轮：约束 (how) / 第 3 轮：范围 (scope)
+5. **先探索** — 提问前先检查 package.json、现有结构
+
+### 1-3. 一致性确认
+
+在进入 DECOMPOSE 之前：
+- 目标用一句话概括
+- 技术栈/方法达成一致
+- MVP 范围已定义
+- 用户确认"继续"
+
+### 1-4. 假设检测（Red Flag 清单）
+
+**如果你第一次读就觉得完全理解了，那你很可能没有。**
+
+检查以下隐藏假设：
+
+| Red Flag | 问自己的问题 |
+|----------|------------|
+| "他们显然想要 X" | 他们实际说了 X 吗？还是我在推测？ |
+| "这跟 Y 类似" | 区别是什么？相似 ≠ 相同 |
+| "标准做法是…" | 这是用户想要的，还是我的默认？ |
+| "我了解这个代码库" | 上次确认是什么时候？有没有变化？ |
+| "这是个简单的修复" | 我读了周围的代码吗？什么可能会崩？ |
+| "他们没提 Z，所以不需要" | 还是他们认为 Z 是理所当然的？ |
+
+**假设检测触发器：**
+- 用户请求 < 2 句 → 可能缺少上下文。先探索。
+- 未提及文件/函数名 → [不充分]。必须提问。
+- "随便"、"简单"、"快速" → 复杂度被低估。
+- "做成像 X 一样" → X 的哪个方面？需要澄清。
+
+---
+
+## 2. DECOMPOSE (分解) — 分解协议
+
+### 2-1. 分解触发器 (必须)
+
+当任务影响 3 个以上文件或比较复杂时：
+- 不要立即实现 — **先列出步骤**
+- 每个步骤必须可独立验证
+- 告知用户："我将把这分解为 N 个步骤"
+
+### 2-2. 五个分解原则
+
+1. **单元大小**：2-5 分钟（测试/实现/验证作为单独步骤）
+2. **测试优先**：每个单元中测试先于实现
+3. **独立验证**：每个单元都有通过标准
+4. **指定文件**：每个任务列出要创建/修改的文件
+5. **标注依赖**：如果单元依赖于前一个单元则标记
+
+### 2-3. 复杂度级别
+
+- **[简单]** 1-2 个文件，指令清晰 → 无需分解
+- **[中等]** 3-5 个文件，一个功能 → 2-3 批次
+- **[复杂]** 6 个以上文件，多个功能 → 5 个以上批次，需要计划文件
+- **[复杂系统]** 范围不明确 → 需要 UNDERSTAND → 缩小范围，然后分解
+
+### 2-4. 复杂系统策略
+
+"不要事先计划一切。计划你能理解的，通过执行学习。"
+
+1. 探索式分解 — 从你理解的部分开始
+2. 渐进式扩展 — 根据结果调整下一步分解
+3. 重新评估循环 — 每批次后验证方向
+
+### 2-5. 计划文件持久化
+
+将多步骤计划保存为 markdown：
+- **路径**：`docs/plans/YYYY-MM-DD-<主题>.md`
+- **任务粒度**：每个 2-5 分钟
+- **指定文件**：每个任务的创建/修改/测试文件路径
+
+**计划文件模板：**
+
+```markdown
+## Goal
+一句话：做什么以及为什么。
+
+## Architecture
+技术栈、关键决策，2-3 句。
+
+## Batch 1: [名称]
+- [ ] Task 1.1: [描述] → `path/to/file`
+  - 测试: `path/to/test` — [验证什么]
+  - 通过标准: [具体断言]
+- [ ] Task 1.2: ...
+- [ ] Task 1.3: ...
+
+## Batch 2: [名称]
+- [ ] Task 2.1: ...
+
+## 风险 / 未决问题
+- [已知的不确定性或潜在阻塞]
+```
+
+---
+
+## 3. EXECUTE (执行) — 执行协议
+
+### 3-1. 批次执行 + 检查点
+
+1. **批次大小**：每批 3-4 个任务
+2. **检查点**：每批后报告结果 + 等待用户反馈
+3. **报告内容**：完成了什么 / 验证结果 / 下一批预览
+4. **遇到阻塞时**：立即停止并报告（不要猜测）
+
+### 3-2. TDD Iron Law
+
+1. 先写一个失败的测试
+2. 写最少的代码来通过测试
+3. 没有测试不提交
+4. 没有新鲜验证证据不声明完成
+
+### 3-3. 系统化调试
+
+| 步骤 | 行动 | 输出 |
+|------|------|------|
+| 1. 根本原因调查 | 仔细阅读错误 → 重现 → 检查最近更改 | 假设 |
+| 2. 模式分析 | 找到工作的类似代码 → 比较差异 | 差异列表 |
+| 3. 假设验证 | 单一假设 → 最小更改 → 一次测试一个 | 结果 |
+| 4. 实施 | 写失败测试 → 单一修复 → 验证 | 修复完成 |
+
+**3 次修复失败后：停止。重新考虑方法。**
+
+### 3-4. 自我纠正
+
+- 同一文件编辑 3 次以上 → "可能在打转。调查根本原因。"
+- 编辑计划外文件 → "需要更改范围吗？"
+- 连续 3 次测试失败 → "方法有问题。回到 UNDERSTAND。"
+- 需要新包 → "与用户确认"
+- 自主执行 5 轮 → "继续前报告进度"
+- 给变通方案加变通方案 → "设计问题。退一步。"
+- 复制类似代码 3 次以上 → "需要抽象？与用户确认。"
+
+### 3-5. 范围守卫
+
+**只改请求的。不多也不少。**
+
+修改代码前，通过此过滤器：
+
+1. **是明确请求的更改吗？** → 继续
+2. **是使请求的更改生效所必需的吗？** → 继续
+3. **是工作中发现的改进点吗？** → 停止。记录但不做。
+4. **是"顺便"整理吗？** → 停止。这不是你现在的工作。
+
+**范围守卫违规（抓住自己）：**
+- 添加用户没要求的错误处理
+- 为了"一致性"重构相邻代码
+- 给没碰过的文件加注释/文档
+- 修 bug 时升级依赖
+- 添加超出规定范围的功能
+
+**感到诱惑时：** 给用户留个备注。"我注意到 X 可以改进。当前任务完成后要处理吗？"
+
+---
+
+## 4. CHECKPOINT (检查点) — 确认协议
+
+### 4-1. 批次检查点
+
+每批次后：
+- 报告完成的内容
+- 报告验证结果
+- 预览下一批次
+- "继续吗？"
+
+### 4-2. 方向变更
+
+用户说"改变方向" → 返回 UNDERSTAND
+用户说"停在这里" → 干净退出
+
+---
+
+## 5. 合理化防御
+
+如果这些借口出现在脑海中，**那就是警告信号**。停止并回到原则：
+
+| 借口 | 现实 |
+|------|------|
+| "太简单无需分解" | 3 个以上文件 = 总是分解 |
+| "不想打扰用户" | 如果模糊，必须提问。不许猜测 |
+| "我稍后添加测试" | TDD。测试先行 |
+| "就这一次" | 没有例外 |
+| "用户说继续" | 一次批准 ≠ 无限授权 |
+| "他们显然想要这个" | 确认。假设是所有 bug 的根源 |
+| "顺便…" | 范围蔓延。专注当前任务 |
+| "差不多对了" | 差不多 ≠ 正确。精确验证 |
+| "脑子里跑通了" | 跑测试。思想实验不算证据 |
+| "现有代码反正很乱" | 只改请求的。其余记录备忘 |
+
+## 6. 完成声明规则
+
+没有验证不要使用这些短语：
+- ❌ "将会"、"应该"、"可能"、"似乎"
+
+声明完成前必须：
+1. **IDENTIFY (识别)** — 什么证明完成？
+2. **RUN (运行)** — 执行相关测试/构建
+3. **READ (阅读)** — 直接检查输出
+4. **CLAIM (声明)** — 仅基于证据声明
+<!-- PRISM:END -->

package/templates/runners/commit-guard.mjs

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+import { runHook } from '../lib/adapter.mjs';
+import { commitGuard } from '../rules/commit-guard.mjs';
+runHook('commit-guard', 'PreToolUse', commitGuard);

package/templates/runners/debug-loop.mjs

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+import { runHook } from '../lib/adapter.mjs';
+import { debugLoop } from '../rules/debug-loop.mjs';
+runHook('debug-loop', 'PostToolUse', debugLoop);

package/templates/runners/scope-guard.mjs

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+import { runHook } from '../lib/adapter.mjs';
+import { scopeGuard } from '../rules/scope-guard.mjs';
+runHook('scope-guard', 'PostToolUse', scopeGuard);

package/templates/runners/test-tracker.mjs

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+import { runHook } from '../lib/adapter.mjs';
+import { testTracker } from '../rules/test-tracker.mjs';
+runHook('test-tracker', 'PostToolUse', testTracker);

package/templates/settings.json

@@ -0,0 +1,48 @@
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node .claude/hooks/commit-guard.mjs",
+            "timeout": 5
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Edit|Write",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node .claude/hooks/debug-loop.mjs",
+            "timeout": 5
+          }
+        ]
+      },
+      {
+        "matcher": "Edit|Write",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node .claude/hooks/scope-guard.mjs",
+            "timeout": 5
+          }
+        ]
+      },
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node .claude/hooks/test-tracker.mjs",
+            "timeout": 5
+          }
+        ]
+      }
+    ]
+  }
+}