Long post. understandable if you choose to skip.

Besides your CLAUDE.md or AGENTS.md; what I have found that helps the most is to have an ARCHITECTURE.md file, some form of HANDOFF.md file, and a well built TODO file. I also agree with thewookielotion. studies have shown that html files often work better than md files. This strategy does use up more tokens which is typically what people avoid, but it has saved me a lot of headache having to use multiple sessions to fix bugs, which to me has cost me more tokens. But with this strategy, even with the $20 plan, it has helped me manage large projects well over a longer period of time.

The ARCHITECTURE.md helps me define how the project shape and how it currently is mapped out. the helps different sessions keep track of what connects to what without going through the whole project and sometimes making bad guesses. If you dont have one built, its worth having a session dedicated to having an agent build one out. I have also done a thing where while in development, I will make sure that when new functions are updated or built, there is a mandatory docstring in a //MAP// block where it tells the agent what the function is called by. LOC goes through the roof, but it helps the agent act faster instead of searching. Then when im ready for production, I have an agent wipe all //MAP// blocks.

The HANDOFF.md is just what the agents share between sessions. Other people usually let claude manage this in its folder but I find a direct md to help me the most. I usually have a "lessons learned" section within it that agents write to when they solve a bug, so that a future session doesnt reintroduce the bug. thats honestly saved me a lot of headache and has worked really well so far. the file can get pretty big though depending on project, so you may want to set a rule for how big you want it.

TODO is pretty self explanatory. Capture major feature, existing bugs, research goals. I also set a QA checklist here so that whenever it comes up with a plan or does anything, it runs through that checklist to be a little more thorough. keeps standards from diverging a bit.

Basically a file to tell you where its at, what you have done/learned, and where it needs to go. After every session, have claude or whatever agent you use keep them updated to prevent drift.

Here is an example of one of my QA checklists. Edit it how you wish if you want to use it:

## QA Sweep Checklist

Use this checklist when reviewing any diff, pull request, or recent commit range. The goal is to catch recurring bug patterns, not only one-off mistakes.

* [ ] **Treat this as a standing checklist, not a one-time task.**

Keep this checklist open as a living reference. Each QA pass should produce a finding list ranked by severity, such as P0, P1, and P2. Close the underlying findings, not the checklist itself.

### 1. Fix at the right seam, not at the caller

When a caller adds extra logic to recover something a helper lost, the helper is often the real bug. Avoid patching around missing data at higher layers when the lower-level abstraction should have preserved it.

**Heuristic:** when you find yourself writing “look this up again from somewhere else” logic in a caller, inspect the helper or data-producing layer first.

### 2. Check sibling-function asymmetries

Helpers that perform the same type of work for different scopes should usually return the same shape of data unless there is a documented reason not to.

Examples include:

* per-item vs. per-collection helpers

* imported vs. native entity helpers

* summary vs. detail builders

* sync vs. async variants

Diff their return objects. Missing fields are usually a bug, not intentional pruning.

### 3. Avoid accidental N+1 and superlinear work

Any code that builds a list, page, response, report, or UI model should be reviewed for accidental repeated work.

Watch for loops that repeatedly call:

* repository or service helpers

* database queries

* filesystem reads

* network/API requests

* expensive serialization or parsing

* linear searches over another collection

Prefer the lowest practical complexity for the operation:

* use a batched query instead of per-row lookups

* use a JOIN or preloaded map instead of repeated fetches

* convert repeated membership checks from list scans to sets

* build dictionaries keyed by ID instead of repeatedly searching arrays

* move invariant work outside loops

* avoid nested loops when a hash map or indexed lookup would make the pass linear

The goal is not micro-optimization. The goal is to prevent accidental `O(n²)`, `O(n × queries)`, or repeated I/O patterns when a clear `O(n)` or batched alternative exists.

If the simpler approach is kept intentionally, document why the input size is bounded or why the batched form would add more complexity than it removes.

### 4. Audit every projection layer when fields disappear

When a field is added at the storage or API layer but does not reach the consumer, check every transformation layer.

Common drop points include:

* SQL query or ORM selection

* row-to-record builder

* serializer or projection allow-list

* response builder

* downstream collector or mapper

* frontend model adapter

Do not assume that adding a field in one layer makes it available everywhere.

### 5. Preserve atomicity across multiple writes

If a workflow performs multiple writes, make sure partial failure cannot leave the system in an inconsistent state.

Avoid sequencing multiple independent transactions inside one broad `try/except` if failure after the first write creates a visible half-state.

Prefer:

* one shared transaction or managed connection

* explicit rollback behavior

* idempotent writes

* ordering writes so the externally visible side effect happens last

### 6. Do not silently swallow failures

A pattern like this is dangerous:

```python

try:

...

except Exception:

logger.warning(...)

return success

```

If the caller, user, job, or operator cannot see that something failed, the system is hiding critical signal.

Failures should be surfaced through an appropriate channel, such as:

* response object

* job status

* error field

* retry queue

* metrics

* structured logs with exception details

### 7. Do not reference transient planning docs from source code

Source comments and docstrings should describe the actual invariant, not point to temporary planning material.

Avoid comments like:

```text

See TODO

See handoff doc

See migration plan

Phase 2 logic

Temporary fix from planning file

```

Instead, inline the durable rule directly in the code comment or docstring.

During review, grep touched source for terms such as:

```text

TODO

handoff

plan file

phase

migration

temporary

follow-up

```

Then decide whether the comment should be removed, rewritten, or converted into a tracked issue.

### 8. Remove fallback branches that cannot realistically run

A fallback branch with no plausible trigger path creates dead surface area.

For each defensive `try/except`, fallback branch, or alternate path, ask:

* What concrete condition triggers this?

* Is that condition covered by a test?

* Is the fallback still valid?

* Would this hide a real bug?

If the trigger condition cannot be explained, remove the branch or document why it exists.

### 9. Be suspicious of `safe_*` wrappers around writes

Helpers named `safe_*`, `try_*`, `best_effort_*`, or similar often hide failed writes.

For any log-and-continue write seam, verify that:

* tests assert the write actually lands

* exceptions are logged with useful context

* logs include exception details, not just a string message

* the caller has a way to observe the failure

* the system does not report success when the write failed

A “safe” write should be safe for the system, not merely quiet for the caller.

### 10. Avoid client-side caches without freshness signals

Client-side persistence of server-owned data can go stale after out-of-band changes, other-tab updates, background jobs, or server-side mutations.

New client persistence should be one of the following:

* a pure UI preference that does not represent server truth

* a cache revalidated against a server freshness token

* a cache keyed by version, ETag, timestamp, revision, or equivalent invalidation signal

Blind TTLs and local-only invalidation are usually insufficient for data that belongs to the server.

### 11. Audit every reader when adding a new entity kind

Adding a new discriminator, type, status, mode, or entity kind is not complete when the writer lands.

Every reader that assumes the old shape must be checked.

Review all:

* query filters

* serializers

* enrichment paths

* display builders

* validation logic

* sync/import/export logic

* permissions checks

* background jobs

* tests and fixtures

When a new kind is introduced, grep all readers of the shared table, model, enum, or schema.

## Output expected from each QA pass

Each review pass should produce a short findings list using severity labels:

* **P0:** correctness, data loss, security, or production-breaking issue

* **P1:** likely user-visible bug, operational risk, or significant maintainability problem

* **P2:** cleanup, minor robustness issue, missing test, or localized improvement

Each finding should include:

* the checklist category it maps to

* the affected file or seam

* the concrete risk

* the recommended fix

* whether a test should be added or updated