- project documentation

- clear rules

- tight feedback loops

- small scoped tasks

- verification at every step

---

A single journal file conflates different kinds of information and becomes noise over time.

Separate memory by type:

- **User context** — who is working on this, their expertise, what they care about. Helps calibrate explanation depth and framing.

- **Feedback** — corrections and confirmations, each with a *why*. Record both directions: if you only save corrections, you avoid past mistakes but drift away from approaches that were already validated. The *why* lets edge cases be judged rather than rules applied blindly.

- **Project state** — current goals, blockers, parked ideas, open questions, deadlines.

Keep these in separate files. Load only what is relevant to the current session.

Keep sessions short and let project files carry continuity instead.

- skills you actively built — things you understood, debugged, designed, or decided yourself

- investigations, debugging work, and tests you drove

- decisions you made and why they mattered

- outcomes that could later become resume bullets

A task where the AI generated code and you approved it is not the same as a skill you hold. Be honest about the distinction.

When instructions conflict, use this priority order:

1. Explicit user request in current session

2. Security and safety constraints

3. Architecture and design documents

4. Project rules (`CLAUDE.md`)

5. Inline code comments and local conventions

6. TODO items and journals

7. Historical decisions recorded in memory files

If conflicts remain unresolved:

- stop

- explain the conflict

- ask for clarification

---

Before changing code:

- identify the relevant subsystem

- read surrounding code

- identify invariants and conventions

- check whether similar patterns already exist elsewhere in the project

- understand why the current implementation exists

Do not immediately rewrite unfamiliar code.

Matching established project patterns is usually more important than introducing a theoretically cleaner abstraction.

---

Before creating new abstractions, helpers, wrappers, services, or utilities:

- check whether equivalent functionality already exists

- extend existing systems where reasonable

- avoid creating duplicate patterns

AI tools frequently introduce redundant abstractions because local generation optimises for immediate completion rather than long-term maintainability.

- requirements conflict

- the change may cause data loss

- behaviour is ambiguous

- security implications are unclear

- architectural intent cannot be inferred confidently

- multiple reasonable implementations exist with materially different tradeoffs

---

AI should optimise for:

- maintainability

- correctness

- clarity

over speed of completion.

A slower correct change is preferable to a fast unstable one.

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

- state the uncertainty

- explain what information is missing

- suggest ways to verify

---

Preserve intentional diagnostics and documentation.

- Keep existing comments, debug output, and logging unless removal is explicitly requested.

- Prefer minimal, reviewable diffs.

Before making architectural changes:

- explain the reasoning

- explain tradeoffs

- identify risks

- confirm assumptions against existing design docs

If any files are generated artefacts — from templates, build pipelines, or code generators — document this prominently.

- Do not edit generated files directly.

- Fixes belong in the template source, not the generated output.

- The AI will edit whatever file it can find unless explicitly told otherwise.

Before pasting any content into an AI session:

---

Running the code is what catches this.

Static review alone is not sufficient, because a hallucinated method name is syntactically indistinguishable from a real one.

If verification cannot be performed:

- say so explicitly

- explain what remains unverified

---

Generated code is syntactically plausible but may contain:

Tests verify behaviour, not safety.

When AI suggests adding a new package or dependency:

- verify it exists

- verify it is actively maintained

- verify it has no known CVEs before adding it

AI-contributed code accumulates, and issues missed initially may only surface in combination with later changes.

- when a significant feature completes

- when dependencies are updated

- security patterns listed above

- accidentally committed credentials or sensitive data

- unnecessary or unsafe dependencies added on AI suggestion

Record each review in the project journal:

- what was checked

- what was found

- what was fixed

Approving one action does not authorise the same action in a different context.

Confirm risky or irreversible operations explicitly each time:

- pushing to a remote

- dropping or overwriting data

- force operations

- modifying shared infrastructure

---

- why decisions were made

- what alternatives were rejected

- what uncertainties remain

- what future work was intentionally deferred

Do not record every tiny edit.

At the start of each session:

1. Read the journal.

2. Check parked ideas and open questions.

3. Note current project state before asking or being asked what to work on.

---

project/

├── CLAUDE.md

│ ├── architecture.md

│ ├── design.md

│ ├── workflows.md

└── src/

Once the project is structured properly, prompts can stay extremely small:

Read the project docs and journal.

Complete the highest priority TODO item.

Use TDD.

Update journal.md if new lessons or decisions emerge.