claude-prism 0.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.ko.md +429 -0
- package/README.md +500 -0
- package/bin/cli.mjs +158 -0
- package/hooks/commit-guard.mjs +48 -0
- package/hooks/debug-loop.mjs +67 -0
- package/hooks/scope-guard.mjs +61 -0
- package/hooks/test-tracker.mjs +61 -0
- package/lib/adapter.mjs +89 -0
- package/lib/config.mjs +54 -0
- package/lib/installer.mjs +439 -0
- package/lib/omc.mjs +38 -0
- package/lib/state.mjs +52 -0
- package/lib/utils.mjs +8 -0
- package/package.json +33 -0
- package/templates/commands/claude-prism/checkpoint.md +34 -0
- package/templates/commands/claude-prism/doctor.md +42 -0
- package/templates/commands/claude-prism/help.md +42 -0
- package/templates/commands/claude-prism/plan.md +52 -0
- package/templates/commands/claude-prism/prism.md +84 -0
- package/templates/commands/claude-prism/stats.md +36 -0
- package/templates/rules.en.md +226 -0
- package/templates/rules.ja.md +226 -0
- package/templates/rules.ko.md +226 -0
- package/templates/rules.zh.md +226 -0
- package/templates/runners/commit-guard.mjs +4 -0
- package/templates/runners/debug-loop.mjs +4 -0
- package/templates/runners/scope-guard.mjs +4 -0
- package/templates/runners/test-tracker.mjs +4 -0
- package/templates/settings.json +48 -0
|
@@ -0,0 +1,52 @@
|
|
|
1
|
+
# /claude-prism:plan — Plan File Management
|
|
2
|
+
|
|
3
|
+
When this command is invoked:
|
|
4
|
+
|
|
5
|
+
## List Plans
|
|
6
|
+
|
|
7
|
+
1. **Check** if `docs/plans/` exists. If not, report "No plans directory found. Create one with `/claude-prism:plan create <topic>`."
|
|
8
|
+
2. **Scan** `docs/plans/` for all `.md` files
|
|
9
|
+
3. **Show each plan** with:
|
|
10
|
+
- Filename and date
|
|
11
|
+
- Goal (first line after `## Goal`)
|
|
12
|
+
- Progress: count [x] vs [ ] tasks
|
|
13
|
+
- Status: Complete / In Progress / Not Started
|
|
14
|
+
|
|
15
|
+
## Create New Plan
|
|
16
|
+
|
|
17
|
+
If user requests a new plan:
|
|
18
|
+
|
|
19
|
+
1. **Determine topic** from user's description
|
|
20
|
+
2. **Create file** at `docs/plans/YYYY-MM-DD-<topic>.md`
|
|
21
|
+
3. **Use UDEC template** (adapt language to project's `.claude-prism.json` language setting):
|
|
22
|
+
|
|
23
|
+
```
|
|
24
|
+
## Goal
|
|
25
|
+
One sentence: what and why.
|
|
26
|
+
|
|
27
|
+
## Architecture
|
|
28
|
+
Tech stack, key decisions, 2-3 sentences.
|
|
29
|
+
|
|
30
|
+
## Batch 1: [Name]
|
|
31
|
+
- [ ] Task 1.1: [Description] → `path/to/file`
|
|
32
|
+
- Test: `path/to/test` — [what to verify]
|
|
33
|
+
- Pass criterion: [specific assertion]
|
|
34
|
+
- [ ] Task 1.2: ...
|
|
35
|
+
|
|
36
|
+
## Batch 2: [Name]
|
|
37
|
+
- [ ] Task 2.1: ...
|
|
38
|
+
|
|
39
|
+
## Risks / Open Questions
|
|
40
|
+
- [Known uncertainties or potential blockers]
|
|
41
|
+
```
|
|
42
|
+
|
|
43
|
+
4. **Announce**: "Plan file created. Use /claude-prism:prism to start execution."
|
|
44
|
+
|
|
45
|
+
## View Specific Plan
|
|
46
|
+
|
|
47
|
+
If user specifies a plan file:
|
|
48
|
+
|
|
49
|
+
1. **Read** the specified plan file
|
|
50
|
+
2. **Show progress** with completion percentage
|
|
51
|
+
3. **Highlight** current batch (first batch with incomplete tasks)
|
|
52
|
+
4. **List blockers** from "리스크 / 미결 사항" section
|
|
@@ -0,0 +1,84 @@
|
|
|
1
|
+
# /claude-prism:prism — Problem Decomposition
|
|
2
|
+
|
|
3
|
+
When this command is invoked, follow the UDEC framework strictly:
|
|
4
|
+
|
|
5
|
+
## U — UNDERSTAND
|
|
6
|
+
|
|
7
|
+
1. **Explore first**: Read package.json, project structure, related files before asking anything
|
|
8
|
+
2. **Assess information sufficiency**:
|
|
9
|
+
- [Sufficient] Specific file, function, symptom mentioned → skip to DECOMPOSE
|
|
10
|
+
- [Partial] Direction clear but details missing → explore then ask 1-2 questions
|
|
11
|
+
- [Insufficient] Abstract, vague, multiple interpretations → must ask questions first
|
|
12
|
+
3. **Check for hidden assumptions** (Red Flag Detection):
|
|
13
|
+
|
|
14
|
+
| Red Flag | Question to Ask Yourself |
|
|
15
|
+
|----------|-------------------------|
|
|
16
|
+
| "Obviously they want X" | Did they actually say X? Or is it my inference? |
|
|
17
|
+
| "Similar to Y" | What are the differences? Similar ≠ identical |
|
|
18
|
+
| "Standard approach is..." | Is this what the user wants, or my default? |
|
|
19
|
+
| "Simple fix" | Did I read surrounding code? What could break? |
|
|
20
|
+
| Request < 2 sentences | Likely missing context. Explore first. |
|
|
21
|
+
| No file/function names | [Insufficient]. Must ask. |
|
|
22
|
+
| "just", "simply" | Complexity being underestimated |
|
|
23
|
+
|
|
24
|
+
4. **Question rules** (if questions needed):
|
|
25
|
+
- One question at a time
|
|
26
|
+
- Multiple choice with 2-3 options + recommendation
|
|
27
|
+
- Include reasoning based on code exploration
|
|
28
|
+
- Maximum 3 rounds of questions
|
|
29
|
+
5. **Confirm alignment**: Summarize goal in one sentence, get user approval
|
|
30
|
+
6. **Analysis-only requests**: If no code change is needed (architecture review, cause analysis, investigation), report findings and ask: "Further action needed?" Do NOT proceed to D/E/C unless the user requests implementation.
|
|
31
|
+
|
|
32
|
+
## D — DECOMPOSE
|
|
33
|
+
|
|
34
|
+
7. **Assess complexity** (consider BOTH file count AND logic complexity):
|
|
35
|
+
- [Simple] 1-2 files, minor changes (<50 LOC) → execute directly, no decomposition needed
|
|
36
|
+
- [Medium] 3-5 files, OR 1-2 files with significant logic changes (50-150 LOC) → 2-3 batches
|
|
37
|
+
- [Complex] 6+ files, OR substantial architectural changes → 5+ batches, must create plan file
|
|
38
|
+
- [Complex system] Unclear scope → reduce scope first, then decompose
|
|
39
|
+
8. **Create batches** following the 5 principles:
|
|
40
|
+
- Unit size: 2-5 minutes each (test/implement/verify as separate steps)
|
|
41
|
+
- Test first: test before implementation in each unit
|
|
42
|
+
- Independent verification: each unit has a pass criterion
|
|
43
|
+
- Files specified: list files to create/modify per unit
|
|
44
|
+
- Dependencies noted: mark if unit depends on a previous one
|
|
45
|
+
9. **Save plan** to `docs/plans/YYYY-MM-DD-<topic>.md`
|
|
46
|
+
10. **Get approval**: "Proceed with this plan?"
|
|
47
|
+
|
|
48
|
+
## E — EXECUTE
|
|
49
|
+
|
|
50
|
+
11. Execute one batch at a time (3-4 tasks per batch)
|
|
51
|
+
12. Follow TDD: write failing test → implement → verify → commit
|
|
52
|
+
13. **Scope Guard**: Before each change, ask: "Was this requested?" If no → don't do it
|
|
53
|
+
14. **Self-correction triggers**:
|
|
54
|
+
- Same file edited 3+ times **on the same region/logic** → stop, investigate root cause (progressive edits across different regions — imports, logic, JSX — are normal)
|
|
55
|
+
- File not in plan → pause, ask about scope change
|
|
56
|
+
- 3 consecutive test failures → stop, reconsider approach
|
|
57
|
+
- New package needed → ask user first
|
|
58
|
+
- Adding workarounds on workarounds → design problem, step back
|
|
59
|
+
15. **Verification scoping**: When running build checks (tsc, lint, etc.), filter output to only changed files. Pre-existing errors in other files are not your concern. Example: `tsc --noEmit 2>&1 | grep -i "<changed-file>"`
|
|
60
|
+
16. **Agent failure recovery**: If a delegated agent partially fails or produces incomplete results:
|
|
61
|
+
1. Verify actual file state (read the file, not just the agent's report)
|
|
62
|
+
2. If partially correct → complete the remaining work directly
|
|
63
|
+
3. If fully wrong → retry with clearer instructions or execute directly
|
|
64
|
+
|
|
65
|
+
## C — CHECKPOINT
|
|
66
|
+
|
|
67
|
+
17. After each batch, report using this format:
|
|
68
|
+
|
|
69
|
+
| Item | Before | After |
|
|
70
|
+
|------|--------|-------|
|
|
71
|
+
| [what changed] | [old behavior] | [new behavior] |
|
|
72
|
+
|
|
73
|
+
18. Include: verification results, files modified, tests status
|
|
74
|
+
19. Ask: "Continue to next batch?"
|
|
75
|
+
20. User can redirect, adjust scope, or stop at any checkpoint
|
|
76
|
+
|
|
77
|
+
## OMC Integration
|
|
78
|
+
|
|
79
|
+
If oh-my-claudecode is detected in this environment:
|
|
80
|
+
- Use `explore` agent for codebase exploration in the UNDERSTAND phase
|
|
81
|
+
- Use `architect` agent for complex decomposition decisions
|
|
82
|
+
- Use `executor` agents for parallel batch execution when tasks are independent
|
|
83
|
+
- Use `verifier` agent for checkpoint verification
|
|
84
|
+
- Scope Guard thresholds are automatically raised for sub-agents (8 warn / 12 block vs 4/7)
|
|
@@ -0,0 +1,36 @@
|
|
|
1
|
+
# /claude-prism:stats — Project Statistics
|
|
2
|
+
|
|
3
|
+
When this command is invoked:
|
|
4
|
+
|
|
5
|
+
## Gather Information
|
|
6
|
+
|
|
7
|
+
1. **Read `.claude-prism.json`** for:
|
|
8
|
+
- Language setting
|
|
9
|
+
- Hook configurations and enabled status
|
|
10
|
+
2. **Scan plan files** in `docs/plans/*.md`:
|
|
11
|
+
- Count total files
|
|
12
|
+
- For each plan, count `[x]` (done) vs `[ ]` (pending) tasks
|
|
13
|
+
- Calculate completion percentage
|
|
14
|
+
3. **Detect OMC** (oh-my-claudecode) presence by checking `~/.claude/CLAUDE.md` for `OMC:START` marker
|
|
15
|
+
|
|
16
|
+
## Report Format
|
|
17
|
+
|
|
18
|
+
```
|
|
19
|
+
🌈 claude-prism stats
|
|
20
|
+
|
|
21
|
+
Version: v0.1.0
|
|
22
|
+
Language: ko
|
|
23
|
+
Plans: 3 file(s)
|
|
24
|
+
OMC: ✅ detected
|
|
25
|
+
|
|
26
|
+
Hooks:
|
|
27
|
+
✅ commit-guard (maxTestAge: 300s)
|
|
28
|
+
✅ debug-loop (warn: 3, block: 5)
|
|
29
|
+
✅ test-tracker
|
|
30
|
+
✅ scope-guard (warn: 4/8, block: 7/12)
|
|
31
|
+
|
|
32
|
+
Plans:
|
|
33
|
+
📋 2026-02-15-p3-inspector.md [3/5] 60%
|
|
34
|
+
📋 2026-02-15-p8-templates.md [5/5] 100% ✅
|
|
35
|
+
📋 2026-02-16-p4-token.md [0/4] 0%
|
|
36
|
+
```
|
|
@@ -0,0 +1,226 @@
|
|
|
1
|
+
<!-- PRISM:START -->
|
|
2
|
+
# Prism — AI Coding Problem Decomposition Framework (UDEC)
|
|
3
|
+
|
|
4
|
+
## Core Principle
|
|
5
|
+
|
|
6
|
+
**Never implement what you haven't understood. Never execute what you haven't decomposed.**
|
|
7
|
+
|
|
8
|
+
---
|
|
9
|
+
|
|
10
|
+
## 1. UNDERSTAND — Understanding Protocol
|
|
11
|
+
|
|
12
|
+
### 1-1. Information Sufficiency Assessment (MANDATORY)
|
|
13
|
+
|
|
14
|
+
Before acting on any request, assess first:
|
|
15
|
+
|
|
16
|
+
- **[Sufficient]** Specific file, function, symptom mentioned → skip to DECOMPOSE
|
|
17
|
+
- **[Partial]** Direction clear but details missing → explore code, then ask 1-2 questions
|
|
18
|
+
- **[Insufficient]** Abstract, vague, multiple interpretations → must ask questions first
|
|
19
|
+
|
|
20
|
+
### 1-2. Question Rules
|
|
21
|
+
|
|
22
|
+
1. **One question at a time** — never ask multiple questions simultaneously
|
|
23
|
+
2. **Multiple choice first** — 2-3 options with a recommendation
|
|
24
|
+
3. **Include reasoning** — explore code first, then ask context-aware questions
|
|
25
|
+
4. **Maximum 3 rounds** — Round 1: direction (what) / Round 2: constraints (how) / Round 3: scope
|
|
26
|
+
5. **Explore first** — check package.json, existing structure before asking
|
|
27
|
+
|
|
28
|
+
### 1-3. Alignment Confirmation
|
|
29
|
+
|
|
30
|
+
Before moving to DECOMPOSE:
|
|
31
|
+
- Goal summarized in one sentence
|
|
32
|
+
- Tech stack/approach agreed
|
|
33
|
+
- MVP scope defined
|
|
34
|
+
- User confirmed "proceed"
|
|
35
|
+
|
|
36
|
+
### 1-4. Assumption Detection (Red Flag Checklist)
|
|
37
|
+
|
|
38
|
+
**If you think you understand fully on first read, you probably don't.**
|
|
39
|
+
|
|
40
|
+
Pause and check for these hidden assumptions:
|
|
41
|
+
|
|
42
|
+
| Red Flag | Question to Ask Yourself |
|
|
43
|
+
|----------|------------------------|
|
|
44
|
+
| "Obviously they want X" | Did they actually say X? Or am I inferring? |
|
|
45
|
+
| "This is similar to Y" | What are the differences? Similar ≠ identical |
|
|
46
|
+
| "The standard approach is..." | Is that what the user wants, or what I default to? |
|
|
47
|
+
| "I know how this codebase works" | When did I last verify? Has it changed? |
|
|
48
|
+
| "This is a simple fix" | Have I read the surrounding code? What might break? |
|
|
49
|
+
| "They didn't mention Z, so it's not needed" | Or did they assume Z was obvious? |
|
|
50
|
+
|
|
51
|
+
**Assumption Detection Triggers:**
|
|
52
|
+
- User request < 2 sentences → likely missing context. Explore first.
|
|
53
|
+
- No file/function names mentioned → [Insufficient]. Must ask.
|
|
54
|
+
- Words like "just", "simply", "quickly" → complexity is being underestimated.
|
|
55
|
+
- "Make it work like X" → what specific aspect of X? Clarify.
|
|
56
|
+
|
|
57
|
+
---
|
|
58
|
+
|
|
59
|
+
## 2. DECOMPOSE — Decomposition Protocol
|
|
60
|
+
|
|
61
|
+
### 2-1. Decomposition Trigger (MANDATORY)
|
|
62
|
+
|
|
63
|
+
When a task affects 3+ files or is complex:
|
|
64
|
+
- Do NOT implement immediately — **list the steps first**
|
|
65
|
+
- Each step must be independently verifiable
|
|
66
|
+
- Inform user: "I'll break this into N steps"
|
|
67
|
+
|
|
68
|
+
### 2-2. Five Decomposition Principles
|
|
69
|
+
|
|
70
|
+
1. **Unit size**: 2-5 minutes (test/implement/verify as separate steps)
|
|
71
|
+
2. **Test first**: tests come before implementation in each unit
|
|
72
|
+
3. **Independent verification**: each unit has a pass criterion
|
|
73
|
+
4. **Files specified**: each task lists files to create/modify
|
|
74
|
+
5. **Dependencies noted**: mark if a unit depends on a previous one
|
|
75
|
+
|
|
76
|
+
### 2-3. Complexity Levels
|
|
77
|
+
|
|
78
|
+
- **[Simple]** 1-2 files, clear instruction → no decomposition needed
|
|
79
|
+
- **[Medium]** 3-5 files, one feature → 2-3 batches
|
|
80
|
+
- **[Complex]** 6+ files, multiple features → 5+ batches, plan file required
|
|
81
|
+
- **[Complex system]** Unclear scope → UNDERSTAND required → reduce scope, then decompose
|
|
82
|
+
|
|
83
|
+
### 2-4. Complex System Strategy
|
|
84
|
+
|
|
85
|
+
"Don't plan everything upfront. Plan what you can, learn by executing."
|
|
86
|
+
|
|
87
|
+
1. Exploratory decomposition — start with what you understand
|
|
88
|
+
2. Incremental expansion — adjust next decomposition based on results
|
|
89
|
+
3. Re-evaluation loop — verify direction after each batch
|
|
90
|
+
|
|
91
|
+
### 2-5. Plan File Persistence
|
|
92
|
+
|
|
93
|
+
Save multi-step plans as markdown:
|
|
94
|
+
- **Path**: `docs/plans/YYYY-MM-DD-<topic>.md`
|
|
95
|
+
- **Task granularity**: 2-5 minutes each
|
|
96
|
+
- **Files specified**: creation/modification/test file paths per task
|
|
97
|
+
|
|
98
|
+
**Plan File Template:**
|
|
99
|
+
|
|
100
|
+
```markdown
|
|
101
|
+
## Goal
|
|
102
|
+
One sentence: what we're building and why.
|
|
103
|
+
|
|
104
|
+
## Architecture
|
|
105
|
+
Tech stack, key decisions, 2-3 sentences max.
|
|
106
|
+
|
|
107
|
+
## Batch 1: [Name]
|
|
108
|
+
- [ ] Task 1.1: [description] → `path/to/file`
|
|
109
|
+
- Test: `path/to/test` — [what it verifies]
|
|
110
|
+
- Pass criterion: [specific assertion]
|
|
111
|
+
- [ ] Task 1.2: ...
|
|
112
|
+
- [ ] Task 1.3: ...
|
|
113
|
+
|
|
114
|
+
## Batch 2: [Name]
|
|
115
|
+
- [ ] Task 2.1: ...
|
|
116
|
+
|
|
117
|
+
## Risks / Open Questions
|
|
118
|
+
- [Known unknowns or potential blockers]
|
|
119
|
+
```
|
|
120
|
+
|
|
121
|
+
---
|
|
122
|
+
|
|
123
|
+
## 3. EXECUTE — Execution Protocol
|
|
124
|
+
|
|
125
|
+
### 3-1. Batch Execution + Checkpoints
|
|
126
|
+
|
|
127
|
+
1. **Batch size**: 3-4 tasks per batch
|
|
128
|
+
2. **Checkpoint**: report results after each batch + wait for user feedback
|
|
129
|
+
3. **Report content**: what was done / verification results / next batch preview
|
|
130
|
+
4. **On blockers**: stop immediately and report (do not guess)
|
|
131
|
+
|
|
132
|
+
### 3-2. TDD Iron Law
|
|
133
|
+
|
|
134
|
+
1. Write a failing test first
|
|
135
|
+
2. Write minimal code to pass the test
|
|
136
|
+
3. Never commit without tests
|
|
137
|
+
4. Never claim completion without fresh verification evidence
|
|
138
|
+
|
|
139
|
+
### 3-3. Systematic Debugging
|
|
140
|
+
|
|
141
|
+
| Step | Action | Output |
|
|
142
|
+
|------|--------|--------|
|
|
143
|
+
| 1. Root cause investigation | Read error carefully → reproduce → check recent changes | Hypothesis |
|
|
144
|
+
| 2. Pattern analysis | Find working similar code → compare differences | Diff list |
|
|
145
|
+
| 3. Hypothesis testing | Single hypothesis → minimal change → test one at a time | Result |
|
|
146
|
+
| 4. Implementation | Write failing test → single fix → verify | Fix complete |
|
|
147
|
+
|
|
148
|
+
**After 3 failed fixes: STOP. Reconsider the approach.**
|
|
149
|
+
|
|
150
|
+
### 3-4. Self-Correction
|
|
151
|
+
|
|
152
|
+
- Same file edited 3+ times → "Possible thrashing. Investigate root cause."
|
|
153
|
+
- Editing file not in plan → "Scope change needed?"
|
|
154
|
+
- 3 consecutive test failures → "Approach problem. Back to UNDERSTAND."
|
|
155
|
+
- New package needed → "Confirm with user"
|
|
156
|
+
- 5 turns autonomous → "Report progress before continuing"
|
|
157
|
+
- Adding workarounds to fix workarounds → "Design problem. Step back."
|
|
158
|
+
- Copy-pasting similar code 3+ times → "Need abstraction? Ask user."
|
|
159
|
+
|
|
160
|
+
### 3-5. Scope Guard
|
|
161
|
+
|
|
162
|
+
**Only change what was requested. Nothing more, nothing less.**
|
|
163
|
+
|
|
164
|
+
Before modifying any code, pass this filter:
|
|
165
|
+
|
|
166
|
+
1. **Was this change explicitly requested?** → proceed
|
|
167
|
+
2. **Is it required to make the requested change work?** → proceed
|
|
168
|
+
3. **Is it an improvement I noticed while working?** → STOP. Note it, don't do it.
|
|
169
|
+
4. **Is it "while I'm here" cleanup?** → STOP. Not your job right now.
|
|
170
|
+
|
|
171
|
+
**Scope Guard Violations (catch yourself):**
|
|
172
|
+
- Adding error handling the user didn't ask for
|
|
173
|
+
- Refactoring adjacent code "for consistency"
|
|
174
|
+
- Adding comments/docs to untouched files
|
|
175
|
+
- Upgrading dependencies while fixing a bug
|
|
176
|
+
- Adding features beyond what was specified
|
|
177
|
+
|
|
178
|
+
**If tempted:** Note the improvement for the user. Ask: "I noticed X could be improved. Want me to address it after the current task?"
|
|
179
|
+
|
|
180
|
+
---
|
|
181
|
+
|
|
182
|
+
## 4. CHECKPOINT — Confirmation Protocol
|
|
183
|
+
|
|
184
|
+
### 4-1. Batch Checkpoint
|
|
185
|
+
|
|
186
|
+
After each batch:
|
|
187
|
+
- Report what was completed
|
|
188
|
+
- Report verification results
|
|
189
|
+
- Preview next batch
|
|
190
|
+
- "Continue?"
|
|
191
|
+
|
|
192
|
+
### 4-2. Direction Change
|
|
193
|
+
|
|
194
|
+
User says "change direction" → return to UNDERSTAND
|
|
195
|
+
User says "stop here" → clean exit
|
|
196
|
+
|
|
197
|
+
---
|
|
198
|
+
|
|
199
|
+
## 5. Rationalization Defense
|
|
200
|
+
|
|
201
|
+
If any of these excuses come to mind, **that's a warning signal**. Stop and return to principles:
|
|
202
|
+
|
|
203
|
+
| Excuse | Reality |
|
|
204
|
+
|--------|---------|
|
|
205
|
+
| "Too simple to decompose" | 3+ files = always decompose |
|
|
206
|
+
| "Don't want to bother the user" | If vague, must ask. No guessing |
|
|
207
|
+
| "I'll add tests later" | TDD. Tests come first |
|
|
208
|
+
| "Just this once" | No exceptions |
|
|
209
|
+
| "User said to proceed" | One approval ≠ unlimited delegation |
|
|
210
|
+
| "I know what they mean" | Verify. Assumption is the root of all bugs |
|
|
211
|
+
| "While I'm here, let me also..." | Scope creep. Stay on task |
|
|
212
|
+
| "This is close enough" | Close ≠ correct. Verify precisely |
|
|
213
|
+
| "It worked in my head" | Run the test. Thought experiments don't count |
|
|
214
|
+
| "The existing code is messy anyway" | Fix what was asked. Note the rest for later |
|
|
215
|
+
|
|
216
|
+
## 6. Completion Declaration Rules
|
|
217
|
+
|
|
218
|
+
Never use these phrases without verification:
|
|
219
|
+
- ❌ "will", "should", "probably", "seems to"
|
|
220
|
+
|
|
221
|
+
Before declaring completion:
|
|
222
|
+
1. **IDENTIFY** — What proves completion?
|
|
223
|
+
2. **RUN** — Execute the relevant test/build
|
|
224
|
+
3. **READ** — Check the output directly
|
|
225
|
+
4. **CLAIM** — Only declare based on evidence
|
|
226
|
+
<!-- PRISM:END -->
|
|
@@ -0,0 +1,226 @@
|
|
|
1
|
+
<!-- PRISM:START -->
|
|
2
|
+
# Prism — AI コーディング問題分解フレームワーク (UDEC)
|
|
3
|
+
|
|
4
|
+
## 核心原則
|
|
5
|
+
|
|
6
|
+
**理解していないものを実装するな。分解していないものを実行するな。**
|
|
7
|
+
|
|
8
|
+
---
|
|
9
|
+
|
|
10
|
+
## 1. UNDERSTAND (理解) — 理解プロトコル
|
|
11
|
+
|
|
12
|
+
### 1-1. 情報充足性の評価 (必須)
|
|
13
|
+
|
|
14
|
+
リクエストに対応する前に、まず評価せよ:
|
|
15
|
+
|
|
16
|
+
- **[十分]** 特定のファイル、関数、症状が明示されている → DECOMPOSEへスキップ
|
|
17
|
+
- **[部分的]** 方向性は明確だが詳細が不足 → コードを探索してから1-2個質問
|
|
18
|
+
- **[不十分]** 抽象的、曖昧、複数の解釈が可能 → 必ず先に質問
|
|
19
|
+
|
|
20
|
+
### 1-2. 質問ルール
|
|
21
|
+
|
|
22
|
+
1. **一度に一つの質問** — 複数の質問を同時にしない
|
|
23
|
+
2. **選択肢を優先** — 2-3個のオプションと推奨を提示
|
|
24
|
+
3. **根拠を含める** — まずコードを探索してから、文脈に沿った質問をする
|
|
25
|
+
4. **最大3ラウンド** — ラウンド1: 方向性 (what) / ラウンド2: 制約 (how) / ラウンド3: 範囲 (scope)
|
|
26
|
+
5. **探索を先に** — 質問する前にpackage.json、既存構造を確認
|
|
27
|
+
|
|
28
|
+
### 1-3. 合意の確認
|
|
29
|
+
|
|
30
|
+
DECOMPOSEに進む前に確認:
|
|
31
|
+
- ゴールが一文で要約されている
|
|
32
|
+
- 技術スタック/アプローチが合意されている
|
|
33
|
+
- MVP範囲が定義されている
|
|
34
|
+
- ユーザーが「進めて」と確認した
|
|
35
|
+
|
|
36
|
+
### 1-4. 仮定の検出(Red Flagチェックリスト)
|
|
37
|
+
|
|
38
|
+
**最初に読んで完全に理解できたと思ったら、おそらく理解できていない。**
|
|
39
|
+
|
|
40
|
+
以下の隠れた仮定をチェックせよ:
|
|
41
|
+
|
|
42
|
+
| Red Flag | 自問すべきこと |
|
|
43
|
+
|----------|--------------|
|
|
44
|
+
| 「当然Xを望んでいる」 | 実際にXと言ったか?それとも私の推測か? |
|
|
45
|
+
| 「Yと似ている」 | 違いは何か?類似 ≠ 同一 |
|
|
46
|
+
| 「標準的なアプローチは…」 | ユーザーが望むものか、私のデフォルトか? |
|
|
47
|
+
| 「このコードベースを知っている」 | 最後に確認したのはいつ?変更されていないか? |
|
|
48
|
+
| 「簡単な修正だ」 | 周辺のコードを読んだか?何が壊れうるか? |
|
|
49
|
+
| 「Zは言及されなかったから不要」 | Zは当然だと思っていたのでは? |
|
|
50
|
+
|
|
51
|
+
**仮定検出トリガー:**
|
|
52
|
+
- ユーザーリクエスト < 2文 → コンテキスト不足の可能性。まず探索。
|
|
53
|
+
- ファイル/関数名の言及なし → [不十分]。必ず質問。
|
|
54
|
+
- 「ちょっと」「簡単に」「さっと」 → 複雑さが過小評価されている。
|
|
55
|
+
- 「Xのように作って」 → Xのどの側面?明確にせよ。
|
|
56
|
+
|
|
57
|
+
---
|
|
58
|
+
|
|
59
|
+
## 2. DECOMPOSE (分解) — 分解プロトコル
|
|
60
|
+
|
|
61
|
+
### 2-1. 分解トリガー (必須)
|
|
62
|
+
|
|
63
|
+
タスクが3つ以上のファイルに影響するか、複雑な場合:
|
|
64
|
+
- すぐに実装しない — **まずステップをリストアップ**
|
|
65
|
+
- 各ステップは独立して検証可能でなければならない
|
|
66
|
+
- ユーザーに通知: 「これをN個のステップに分割します」
|
|
67
|
+
|
|
68
|
+
### 2-2. 5つの分解原則
|
|
69
|
+
|
|
70
|
+
1. **単位サイズ**: 2-5分 (テスト/実装/検証を別々のステップとして)
|
|
71
|
+
2. **テスト優先**: 各単位でテストが実装より先に来る
|
|
72
|
+
3. **独立した検証**: 各単位に合格基準がある
|
|
73
|
+
4. **ファイル指定**: 各タスクで作成/変更するファイルをリストアップ
|
|
74
|
+
5. **依存関係の記載**: 単位が前の単位に依存する場合はマークする
|
|
75
|
+
|
|
76
|
+
### 2-3. 複雑度レベル
|
|
77
|
+
|
|
78
|
+
- **[シンプル]** 1-2ファイル、明確な指示 → 分解不要
|
|
79
|
+
- **[中程度]** 3-5ファイル、1つの機能 → 2-3バッチ
|
|
80
|
+
- **[複雑]** 6つ以上のファイル、複数の機能 → 5つ以上のバッチ、計画ファイル必須
|
|
81
|
+
- **[複雑系]** 範囲が不明確 → UNDERSTAND必須 → 範囲を縮小してから分解
|
|
82
|
+
|
|
83
|
+
### 2-4. 複雑系戦略
|
|
84
|
+
|
|
85
|
+
「すべてを事前に計画しない。理解できる範囲だけ計画し、実行しながら学ぶ。」
|
|
86
|
+
|
|
87
|
+
1. 探索的分解 — 理解できる部分から始める
|
|
88
|
+
2. 段階的拡張 — 結果に基づいて次の分解を調整
|
|
89
|
+
3. 再評価ループ — 各バッチ後に方向性を確認
|
|
90
|
+
|
|
91
|
+
### 2-5. 計画ファイルの永続化
|
|
92
|
+
|
|
93
|
+
複数ステップの計画をマークダウンとして保存:
|
|
94
|
+
- **パス**: `docs/plans/YYYY-MM-DD-<トピック>.md`
|
|
95
|
+
- **タスク粒度**: 各2-5分
|
|
96
|
+
- **ファイル指定**: タスクごとに作成/変更/テストファイルのパスを記載
|
|
97
|
+
|
|
98
|
+
**計画ファイルテンプレート:**
|
|
99
|
+
|
|
100
|
+
```markdown
|
|
101
|
+
## Goal
|
|
102
|
+
一文:何をなぜ作るか。
|
|
103
|
+
|
|
104
|
+
## Architecture
|
|
105
|
+
技術スタック、主要決定事項、2-3文。
|
|
106
|
+
|
|
107
|
+
## Batch 1: [名前]
|
|
108
|
+
- [ ] Task 1.1: [説明] → `path/to/file`
|
|
109
|
+
- テスト: `path/to/test` — [検証内容]
|
|
110
|
+
- 合格基準: [具体的なアサーション]
|
|
111
|
+
- [ ] Task 1.2: ...
|
|
112
|
+
- [ ] Task 1.3: ...
|
|
113
|
+
|
|
114
|
+
## Batch 2: [名前]
|
|
115
|
+
- [ ] Task 2.1: ...
|
|
116
|
+
|
|
117
|
+
## リスク / 未解決事項
|
|
118
|
+
- [既知の不確実性や潜在的ブロッカー]
|
|
119
|
+
```
|
|
120
|
+
|
|
121
|
+
---
|
|
122
|
+
|
|
123
|
+
## 3. EXECUTE (実行) — 実行プロトコル
|
|
124
|
+
|
|
125
|
+
### 3-1. バッチ実行 + チェックポイント
|
|
126
|
+
|
|
127
|
+
1. **バッチサイズ**: バッチあたり3-4タスク
|
|
128
|
+
2. **チェックポイント**: 各バッチ後に結果を報告 + ユーザーフィードバックを待つ
|
|
129
|
+
3. **報告内容**: 実施内容 / 検証結果 / 次のバッチのプレビュー
|
|
130
|
+
4. **ブロッカー発生時**: 即座に停止して報告 (推測しない)
|
|
131
|
+
|
|
132
|
+
### 3-2. TDD Iron Law
|
|
133
|
+
|
|
134
|
+
1. まず失敗するテストを書く
|
|
135
|
+
2. テストを通過する最小限のコードを書く
|
|
136
|
+
3. テストなしでコミットしない
|
|
137
|
+
4. 新鮮な検証証拠なしで完了を宣言しない
|
|
138
|
+
|
|
139
|
+
### 3-3. 体系的デバッグ
|
|
140
|
+
|
|
141
|
+
| ステップ | アクション | 出力 |
|
|
142
|
+
|---------|-----------|------|
|
|
143
|
+
| 1. 根本原因調査 | エラーを注意深く読む → 再現 → 最近の変更を確認 | 仮説 |
|
|
144
|
+
| 2. パターン分析 | 動作する類似コードを見つける → 差分を比較 | 差分リスト |
|
|
145
|
+
| 3. 仮説検証 | 単一の仮説 → 最小限の変更 → 一つずつテスト | 結果 |
|
|
146
|
+
| 4. 実装 | 失敗するテストを書く → 単一の修正 → 検証 | 修正完了 |
|
|
147
|
+
|
|
148
|
+
**3回の修正失敗後: 停止。アプローチを再考せよ。**
|
|
149
|
+
|
|
150
|
+
### 3-4. 自己修正
|
|
151
|
+
|
|
152
|
+
- 同じファイルを3回以上編集 → 「迷走の可能性。根本原因を調査」
|
|
153
|
+
- 計画にないファイルを編集 → 「スコープ変更が必要か?」
|
|
154
|
+
- 3回連続のテスト失敗 → 「アプローチに問題。UNDERSTANDに戻る」
|
|
155
|
+
- 新しいパッケージが必要 → 「ユーザーに確認」
|
|
156
|
+
- 5ターン自律実行 → 「続行前に進捗を報告」
|
|
157
|
+
- 回避策に回避策を追加 → 「設計の問題。一歩引け」
|
|
158
|
+
- 類似コードを3回以上コピー → 「抽象化が必要?ユーザーに確認」
|
|
159
|
+
|
|
160
|
+
### 3-5. スコープガード
|
|
161
|
+
|
|
162
|
+
**要求されたものだけを変更せよ。それ以上でもそれ以下でもなく。**
|
|
163
|
+
|
|
164
|
+
コードを変更する前に、このフィルターを通過させよ:
|
|
165
|
+
|
|
166
|
+
1. **明示的に要求された変更か?** → 進行
|
|
167
|
+
2. **要求された変更を動作させるために必須か?** → 進行
|
|
168
|
+
3. **作業中に気づいた改善点か?** → 停止。メモするだけ。
|
|
169
|
+
4. **「ついでに」の整理か?** → 停止。今の仕事ではない。
|
|
170
|
+
|
|
171
|
+
**スコープガード違反(自分を捕まえよ):**
|
|
172
|
+
- 要求されていないエラーハンドリングの追加
|
|
173
|
+
- 「一貫性」のための隣接コードのリファクタリング
|
|
174
|
+
- 触れていないファイルへのコメント/ドキュメント追加
|
|
175
|
+
- バグ修正中の依存関係アップグレード
|
|
176
|
+
- 指定された範囲を超える機能追加
|
|
177
|
+
|
|
178
|
+
**誘惑を感じたら:** ユーザーにメモとして残せ。「Xを改善できそうです。現在のタスク完了後に対応しますか?」
|
|
179
|
+
|
|
180
|
+
---
|
|
181
|
+
|
|
182
|
+
## 4. CHECKPOINT (確認) — 確認プロトコル
|
|
183
|
+
|
|
184
|
+
### 4-1. バッチチェックポイント
|
|
185
|
+
|
|
186
|
+
各バッチ後:
|
|
187
|
+
- 完了したものを報告
|
|
188
|
+
- 検証結果を報告
|
|
189
|
+
- 次のバッチをプレビュー
|
|
190
|
+
- 「続行しますか?」
|
|
191
|
+
|
|
192
|
+
### 4-2. 方向転換
|
|
193
|
+
|
|
194
|
+
ユーザーが「方向を変える」と言う → UNDERSTANDに戻る
|
|
195
|
+
ユーザーが「ここで停止」と言う → クリーンな終了
|
|
196
|
+
|
|
197
|
+
---
|
|
198
|
+
|
|
199
|
+
## 5. 合理化防御
|
|
200
|
+
|
|
201
|
+
以下の言い訳が思い浮かんだら、**それは警告信号**。停止して原則に戻れ:
|
|
202
|
+
|
|
203
|
+
| 言い訳 | 現実 |
|
|
204
|
+
|--------|------|
|
|
205
|
+
| 「シンプルすぎて分解不要」 | 3つ以上のファイル = 常に分解 |
|
|
206
|
+
| 「ユーザーを煩わせたくない」 | 曖昧なら必ず質問。推測禁止 |
|
|
207
|
+
| 「後でテストを追加する」 | TDD。テストが先 |
|
|
208
|
+
| 「今回だけ」 | 例外はない |
|
|
209
|
+
| 「ユーザーが進めろと言った」 | 一度の承認 ≠ 無制限の委任 |
|
|
210
|
+
| 「当然これを望んでいる」 | 確認せよ。仮定はすべてのバグの原因 |
|
|
211
|
+
| 「ついでに…」 | スコープクリープ。タスクに集中 |
|
|
212
|
+
| 「大体合っている」 | 大体 ≠ 正確。正確に検証せよ |
|
|
213
|
+
| 「頭の中では動いた」 | テストを実行せよ。思考実験は証拠ではない |
|
|
214
|
+
| 「既存コードがどうせ汚い」 | 要求されたものだけ修正。残りはメモ |
|
|
215
|
+
|
|
216
|
+
## 6. 完了宣言ルール
|
|
217
|
+
|
|
218
|
+
検証なしにこれらのフレーズを使用しない:
|
|
219
|
+
- ❌ 「〜でしょう」「〜はず」「おそらく」「〜のようです」
|
|
220
|
+
|
|
221
|
+
完了を宣言する前に必ず:
|
|
222
|
+
1. **IDENTIFY (特定)** — 何が完了を証明するか?
|
|
223
|
+
2. **RUN (実行)** — 関連するテスト/ビルドを実行
|
|
224
|
+
3. **READ (確認)** — 出力を直接確認
|
|
225
|
+
4. **CLAIM (宣言)** — 証拠に基づいてのみ宣言
|
|
226
|
+
<!-- PRISM:END -->
|