- "Implement changes incrementally and verify after each step."
-
Be brutally honest with me. Don't spare my feelings, don't pander, don't be a sycophant. Skip validation phrases ("great question," "you're absolutely right"). If I'm wrong, say so directly and explain why. If my approach is bad, say so — even if I sound confident or invested in it. If there's a better way to do something, tell me what it is and why. If I'm missing something obvious, point it out plainly.
+
Bad:
+
- "Don't remove logs."
+
- "Don't break things."
-
When you disagree with what I'm asking for, push back before doing it. I'd rather argue for thirty seconds than chase a bad change.
+
Positive instructions produce more reliable behaviour.
-
## Working with my code
+
---
-
- Do not remove comments, debug statements, or logging. They are there on purpose.
-
- If comments, debug output, or logging can be improved, improve them — and tell me what you changed and why. Never silently rewrite them.
-
- If you think a comment, log line, or debug statement should be deleted, tell me and let me decide.
+
### 3. Separate design from implementation
-
## Test-driven development
+
Maintain design documents describing:
+
- architecture
+
- intended workflows
+
- module responsibilities
+
- invariants
+
- interfaces
+
- constraints
-
Write the failing test first. Run it and confirm it fails for the expected reason. Then write the implementation. Then run the test and confirm it passes. Don't write implementation and tests together in one pass — that's not TDD, that's just "code with tests."
+
Then instruct the AI to implement the documented design.
-
## When you get something wrong
+
If implementation repeatedly goes wrong:
+
1. improve the design docs
+
2. improve the rules
+
3. review whether the architecture itself is unclear
-
Don't just patch the immediate symptom:
+
Do not keep patching prompts forever.
-
1. Fix the code.
-
2. If the mistake reveals a missing or unclear rule, improve the project's `CLAUDE.md` (or this global one if it's a cross-project rule).
-
3. Add an entry to the project `journal.md` under "Recent work" describing what broke and what was learned, so the same mistake is less likely next time.
-
4. Tell me what you changed in rules/journal, not just in code.
+
---
-
## Project journal
+
### 4. Use minimal prompts
-
Each project should have a `journal.md` in its memory directory
-
(`~/.claude/projects/<encoded-path>/memory/`). When starting a new project,
-
create this file if it does not exist and add it to `MEMORY.md`.
+
Once project context exists in files:
+
- prompts should be short
+
- prompts should reference TODO items
+
- prompts should focus on one task at a time
-
Structure:
+
Long conversational prompting usually causes drift and inconsistency.
-
```markdown
---
-
name: Project Journal
-
description: Running log of recent work, parked ideas, and open questions — read on startup to catch up quickly
-
type: project
+
+
### 5. Use isolated sessions
+
+
Prefer a new AI session for each feature or task.
+
+
This reduces:
+
- context pollution
+
- stale assumptions
+
- accidental behavioural drift
+
+
Persistent project files should carry the long-term memory instead.
+
---
-
## Parked ideas
-
_None currently._
+
### 6. Prefer incremental changes
-
## Recent work
-
_None yet._
+
Avoid large speculative rewrites.
-
## Open questions
-
_None currently._
-
```
+
Make:
+
- small changes
+
- verify behaviour
+
- review output
+
- continue iteratively
-
Add a pointer to `MEMORY.md`:
+
Large unverified refactors are where AI tools fail hardest.
+
---
+
+
### 7. Use test-driven development where practical
+
+
Preferred workflow:
+
1. write failing test/check
+
2. confirm failure occurs for expected reason
+
3. implement fix
+
4. confirm passing result
+
5. refactor if needed
+
+
Do not generate tests and implementation simultaneously and call it TDD.
+
+
---
+
+
### 8. Treat mistakes as process failures
+
+
When the AI makes a mistake:
+
1. fix the code
+
2. identify why the mistake happened
+
3. improve rules or design docs if needed
+
4. record lessons learned in the project journal
+
+
The goal is not merely fixing bugs.
+
+
The goal is improving the system that produced them.
+
+
---
+
+
# Recommended AI Behaviour Rules
+
+
## General behaviour
+
+
Be direct, technically honest, and precise.
+
+
- Say when something is wrong.
+
- Explain why an approach is risky or poorly designed.
+
- Push back on questionable changes before implementing them.
+
- Distinguish facts from assumptions.
+
- Explain tradeoffs instead of presenting guesses as certainty.
+
- Prefer correctness over agreement.
+
+
Avoid:
+
- flattery
+
- validation phrases
+
- pretending confidence where uncertainty exists
+
+
If uncertain:
+
- state the uncertainty
+
- explain what information is missing
+
- suggest ways to verify
+
+
---
+
+
## Working with code
+
+
Preserve intentional diagnostics and documentation.
+
+
- Keep existing comments, debug output, and logging unless removal is explicitly requested.
+
- Improve comments and logging when useful.
+
- Explain any significant rewrites or cleanup.
+
- Avoid speculative refactors unrelated to the task.
+
- Prefer minimal, reviewable diffs.
+
+
Before making architectural changes:
+
- explain the reasoning
+
- explain tradeoffs
+
- identify risks
+
- confirm assumptions against existing design docs
+
+
---
+
+
## Verification and testing
+
+
After each meaningful change:
+
- run tests
+
- run linters/checks where available
+
- verify expected behaviour
+
- report failures clearly
+
+
Do not claim something works without verification.
+
+
If verification cannot be performed:
+
- say so explicitly
+
- explain what remains unverified
+
+
---
+
+
## Project journal workflow
+
+
Maintain a `journal.md` containing:
+
- recent work
+
- parked ideas
+
- open questions
+
- lessons learned
+
+
Update it whenever:
+
- significant work completes
+
- mistakes reveal missing rules
+
- architectural decisions change
+
- work is deferred
+
+
The journal is operational memory, not a changelog.
+
+
Summarise outcomes and reasoning, not every tiny edit.
+
+
---
+
+
## Recommended project structure
+
+
```text
+
project/
+
├── CLAUDE.md
+
├── journal.md
+
├── docs/
+
│ ├── architecture.md
+
│ ├── design.md
+
│ ├── workflows.md
+
│ └── coding-standards.md
+
├── todo.md
+
└── src/
```
-
- [Project Journal](journal.md) — Running log of recent work, parked ideas, and open questions; read on startup
-
```
-
### Keeping the journal current
+
---
+
+
# Short Operational Prompt
+
+
Once the project is structured properly, prompts can stay extremely small:
+
+
```text
+
Read the project docs and journal.
+
Complete the highest priority TODO item.
+
Use TDD.
+
Update journal.md if new lessons or decisions emerge.
+
```
-
- **Parked ideas** — add an entry (with date) when the user defers something; remove it when acted on or abandoned.
-
- **Recent work** — prepend completed work so the most recent is at the top; summarise at feature/fix level, not commit level.
-
- **Open questions** — add unresolved decisions or things to investigate; clear them when resolved.
+
Most people are still trying to "prompt engineer" around missing project structure.
-
Read `journal.md` at the start of each session to catch up on context before asking the user what to work on.
+
The structure matters far more than clever prompts.