Home A - Z
Menu

Commit 9c95d2

2026-05-18 08:31:22 David Marsh: -/-
ai.md ..
@@ 29,7 29,22 @@
---
- ### 2. Describe desired behaviour positively
+ ### 2. Structure memory by type
+
+ 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.
+ - **References** — where to find things: dashboards, issue trackers, external docs, external credentials or configuration.
+
+ Keep these in separate files. Load only what is relevant to the current session.
+
+ ---
+
+ ### 3. Describe desired behaviour positively
Write rules describing how work should be done rather than only listing forbidden behaviour.
@@ 45,7 60,7 @@
---
- ### 3. Separate design from implementation
+ ### 4. Separate design from implementation
Maintain design documents describing:
- architecture
@@ 66,7 81,7 @@
---
- ### 4. Use minimal prompts
+ ### 5. Use minimal prompts
Once project context exists in files:
- prompts should be short
@@ 75,9 90,16 @@
Long conversational prompting usually causes drift and inconsistency.
+ Define named shorthands for repeatable multi-step sequences. Document the expansion in project rules so the AI learns it rather than guessing.
+
+ Good:
+ - "wrap it up" → check for leaks, update changelog, update docs, commit, push, update journal
+
+ This is more reliable than re-stating the full sequence each time.
+
---
- ### 5. Use isolated sessions
+ ### 6. Use isolated sessions
Prefer a new AI session for each feature or task.
@@ 90,7 112,7 @@
---
- ### 6. Prefer incremental changes
+ ### 7. Prefer incremental changes
Avoid large speculative rewrites.
@@ 104,7 126,7 @@
---
- ### 7. Use test-driven development where practical
+ ### 8. Use test-driven development where practical
Preferred workflow:
1. write failing test/check
@@ 117,7 139,7 @@
---
- ### 8. Treat mistakes as process failures
+ ### 9. Treat mistakes as process failures
When the AI makes a mistake:
1. fix the code
@@ 146,9 168,11 @@
Avoid:
- flattery
- - validation phrases
+ - validation phrases ("great question", "you're absolutely right")
- pretending confidence where uncertainty exists
+ A thirty-second argument before implementing is better than chasing a bad change afterward.
+
If uncertain:
- state the uncertainty
- explain what information is missing
@@ 161,8 185,8 @@
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.
+ - Improve comments and logging when useful, but explain what changed and why.
+ - If a comment, log line, or debug statement should be removed, say so and let the author decide.
- Avoid speculative refactors unrelated to the task.
- Prefer minimal, reviewable diffs.
@@ 172,6 196,16 @@
- identify risks
- confirm assumptions against existing design docs
+ ### Generated files
+
+ 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.
+
+ Document which files are generated and what produces them, in CLAUDE.md or equivalent.
+
---
## Verification and testing
@@ 190,6 224,20 @@
---
+ ## Scope of authorisation
+
+ 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
+
+ Unless standing permission is recorded in a durable config file that both the human and the AI can read, do not assume prior approval carries forward.
+
+ ---
+
## Project journal workflow
Maintain a `journal.md` containing:
@@ 210,12 258,28 @@
---
+ ## Session startup
+
+ 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.
+
+ Do not rely on the AI to remember previous sessions. Assume a cold start every time and let the files provide continuity.
+
+ ---
+
## Recommended project structure
```text
project/
├── CLAUDE.md
├── journal.md
+ ├── memory/
+ │ ├── user.md
+ │ ├── feedback.md
+ │ ├── project.md
+ │ └── references.md
├── docs/
│ ├── architecture.md
│ ├── design.md
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9