225 lines
4.2 KiB
Markdown
225 lines
4.2 KiB
Markdown
# Claude Code State & Control System
|
||
|
||
This document contains **everything you need** to keep Claude Code from losing context, looping, or rewriting history:
|
||
|
||
1. A canonical `PROJECT_STATE.md` file template
|
||
2. A full set of **copy‑paste prompts** for working with Claude Code
|
||
3. Claude Code **hooks / scripts** to automate checkpoints and recovery
|
||
|
||
---
|
||
|
||
## 1️⃣ PROJECT_STATE.md (CANONICAL FILE)
|
||
|
||
Create this file at the root of your repo.
|
||
|
||
```md
|
||
# PROJECT STATE — CANONICAL
|
||
|
||
⚠️ This file is the single source of truth.
|
||
⚠️ Sections marked LOCKED may not be modified unless the user explicitly says "unlock".
|
||
⚠️ Claude must read this file before doing any work.
|
||
|
||
---
|
||
|
||
## Goal (LOCKED)
|
||
<!-- 1–3 sentences. Immutable unless explicitly changed by the user. -->
|
||
|
||
|
||
## Non‑Negotiable Constraints (LOCKED)
|
||
- No re‑evaluation of prior decisions
|
||
- No alternative architectures unless explicitly requested
|
||
- No refactors outside the active task
|
||
- No scope expansion
|
||
|
||
|
||
## Architecture Decisions (LOCKED)
|
||
-
|
||
-
|
||
|
||
|
||
## Current Phase
|
||
<!-- Short name + description -->
|
||
|
||
|
||
## Active Tasks
|
||
<!-- Only tasks Claude is allowed to work on -->
|
||
- [ ]
|
||
- [ ]
|
||
|
||
|
||
## Completed Tasks
|
||
- [x]
|
||
|
||
|
||
## Open Questions (User‑Owned)
|
||
<!-- Claude may not answer these unless asked -->
|
||
-
|
||
|
||
|
||
## Checkpoints (APPEND‑ONLY)
|
||
|
||
### Checkpoint YYYY‑MM‑DD HH:MM
|
||
- What exists:
|
||
- What is missing:
|
||
- Known issues:
|
||
- Next step:
|
||
```
|
||
|
||
---
|
||
|
||
## 2️⃣ CLAUDE CODE PROMPTS (COPY / PASTE)
|
||
|
||
Save this section as `CLAUDE_PROMPTS.md` if you want it separate.
|
||
|
||
---
|
||
|
||
### 🔹 Initialize Project State
|
||
```
|
||
Create or update PROJECT_STATE.md.
|
||
Write the goal, non‑negotiable constraints, architecture decisions, and an initial task list.
|
||
Do NOT write code.
|
||
Do NOT speculate.
|
||
This file is canonical.
|
||
```
|
||
|
||
---
|
||
|
||
### 🔹 Start Any Work Session
|
||
```
|
||
Before doing anything, read PROJECT_STATE.md in full.
|
||
Summarize:
|
||
- Goal
|
||
- Current Phase
|
||
- Active Tasks
|
||
Then proceed with the first unfinished task only.
|
||
Do not modify PROJECT_STATE.md unless explicitly told to.
|
||
```
|
||
|
||
---
|
||
|
||
### 🔹 Execute a Task (No Drift)
|
||
```
|
||
Work only on the selected Active Task.
|
||
Do not introduce new abstractions.
|
||
Do not refactor unrelated code.
|
||
Do not re‑analyze architecture.
|
||
Produce the minimum change required.
|
||
```
|
||
|
||
---
|
||
|
||
### 🔹 Write a Checkpoint
|
||
```
|
||
Write a new checkpoint to PROJECT_STATE.md.
|
||
Append only under the Checkpoints section.
|
||
Do not modify earlier content.
|
||
Summarize truthfully:
|
||
- What exists
|
||
- What is missing
|
||
- Known issues
|
||
- Next step
|
||
```
|
||
|
||
---
|
||
|
||
### 🔹 Context Reset / Recovery
|
||
```
|
||
Clear context.
|
||
Read PROJECT_STATE.md completely.
|
||
Summarize:
|
||
- Goal
|
||
- Current Phase
|
||
- Active Tasks
|
||
Then continue from the next unfinished task.
|
||
```
|
||
|
||
---
|
||
|
||
### 🔹 Scope Guard (When Claude Starts Drifting)
|
||
```
|
||
Stop.
|
||
This is out of scope.
|
||
Re‑read PROJECT_STATE.md.
|
||
Return to the current Active Task.
|
||
```
|
||
|
||
---
|
||
|
||
### 🔹 Lock or Unlock Sections
|
||
```
|
||
Unlock the following section(s):
|
||
- <section name>
|
||
No other sections may be modified.
|
||
```
|
||
|
||
---
|
||
|
||
## 3️⃣ CLAUDE CODE HOOKS / SCRIPTS
|
||
|
||
These assume Claude Code can run shell commands or that you trigger them manually.
|
||
|
||
---
|
||
|
||
### 🧠 Auto‑Checkpoint Script
|
||
Create `checkpoint.sh`
|
||
|
||
```bash
|
||
#!/usr/bin/env bash
|
||
|
||
echo "\n### Checkpoint $(date '+%Y-%m-%d %H:%M')" >> PROJECT_STATE.md
|
||
echo "- What exists:" >> PROJECT_STATE.md
|
||
echo "- What is missing:" >> PROJECT_STATE.md
|
||
echo "- Known issues:" >> PROJECT_STATE.md
|
||
echo "- Next step:" >> PROJECT_STATE.md
|
||
echo "" >> PROJECT_STATE.md
|
||
```
|
||
|
||
Use prompt:
|
||
```
|
||
Run checkpoint.sh and then fill in the new checkpoint accurately.
|
||
```
|
||
|
||
---
|
||
|
||
### 🔁 Session Start Hook
|
||
Create `session_start.md`
|
||
|
||
```md
|
||
Read PROJECT_STATE.md.
|
||
You may not write code until you summarize:
|
||
- Goal
|
||
- Current Phase
|
||
- Active Tasks
|
||
```
|
||
|
||
Paste this at the top of every new Claude Code session.
|
||
|
||
---
|
||
|
||
### 🧯 Emergency Reset Hook
|
||
Create `RESET.md`
|
||
|
||
```md
|
||
STOP ALL WORK.
|
||
Discard assumptions from previous context.
|
||
Read PROJECT_STATE.md in full.
|
||
State what the next correct action is.
|
||
Do not code until confirmed.
|
||
```
|
||
|
||
---
|
||
|
||
## Final Rule (Read This Once)
|
||
|
||
Claude Code is a **stateless executor**, not a planner.
|
||
|
||
This system turns it into:
|
||
- A reliable implementer
|
||
- A resumable worker
|
||
- A non‑looping assistant
|
||
|
||
If Claude starts looping, drifting, or "thinking creatively" — it means the rails weren’t explicit enough.
|
||
|
||
Tighten the rails.
|
||
|