Do not rely on chat history as memory.

Every project should contain:

- design documents

- architecture notes

- coding standards

- workflow rules

- progress journals

- TODO tracking

The AI should read these files at the start of every session.

Prefer Markdown files committed to the repository so both humans and AI share the same source of truth.

- **Feedback** - corrections and confirmations, each with a *why*. Record both positive and negative outcomes. Saving only mistakes prevents repetition, but saving successful patterns preserves approaches already validated.

- **Project state** - current goals, blockers, parked ideas, open questions, deadlines, and active investigations.

- **References** - dashboards, issue trackers, documentation, operational runbooks, and non-sensitive configuration locations.

Keep sessions short and let project files carry continuity instead.

- reviewable diffs

- iterative progress

- review

- revert

- reason about

- debug

- attribute

2. confirm the failure occurs for the expected reason

3. implement the fix

4. confirm the result passes

5. record lessons learned in the project journal

6. tell the user what was corrected and what rule or documentation changed

The file is meant to capture your contribution, the choices, decisions, and direction, including how you wielded the AI, not the execution skills the AI used.

This record is useful for:

- resume and portfolio evidence

- performance reviews

When instructions conflict, use this priority order:

3. Architecture and design documents

4. Project rules (`CLAUDE.md`)

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.

- If a comment, log line, or debug statement should be removed, say so and let the author decide.

- Avoid clever solutions when a straightforward one exists.

- When generating code, avoid reproducing verbatim patterns from known licensed sources.

- In commercial contexts, flag when a generated implementation closely resembles a specific known library or project.

Do not silently fix unrelated issues encountered during a task.

Record them separately if relevant, but keep task scope controlled unless expansion is explicitly approved.

- preserve surrounding style and conventions unless intentionally standardising them

- avoid introducing unrelated formatting churn

- avoid renaming symbols without a clear reason

Consistency reduces maintenance cost.

- 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.

- logged

- retained

- used for training

- never paste credential files, API keys, tokens, or secrets

- sanitise log output and API responses before using them as examples

- treat session contents as if they could be read by anyone

- library methods

- function signatures

- config options

that do not exist.

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.

- explain what it does before they run it

- why decisions were made

- what alternatives were rejected

- what uncertainties remain

- what future work was intentionally deferred

Do not record every tiny edit.

When introducing operational constants, safety rules, retries, timeouts, workarounds, thresholds, or other non-obvious behaviour, record why the decision exists and what evidence supports it.

Future maintainers should be able to determine:

- what problem was observed

- what evidence was gathered

- what behaviour was tested

- why the chosen value or rule was selected

- what uncertainty or tradeoffs still remain

Guidelines:

- Record investigation evidence while the decision is being explored.

- Move stable rationale into durable design or operational documentation.

- Keep inline code comments concise, but make the deeper reasoning traceable.

- Do not leave magic values or unusual behaviour without recoverable context.

For example, if a timeout is increased because testing showed a device regularly completes after the default timeout, record:

- the original failing behaviour

- the observed timing range

- the successful test window

- environmental conditions that affected the result

- any remaining uncertainty or operational risk

Operational behaviour without preserved reasoning eventually becomes superstition.

Assume a cold start every time and let the files provide continuity.

│ ├── user.md

│ ├── feedback.md

│ ├── project.md

│ └── references.md

│ ├── ai-workflow.md

│ ├── ai-rules.md

│ ├── ai-security.md

│ └── project-memory.md

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

Read the project docs and journal.

Complete the highest priority TODO item.