2.8 KiB
2.8 KiB
| name | description |
|---|---|
| state-hygiene | Enforces safe handling of an agent's own durable state/notes files (e.g. state/notes.md, state/TODO.md, or anything else under state/ meant to survive a container restart) - read the file before archiving, overwriting, or pruning it, split resolved work into small dated archive files instead of growing one giant live file, and never shell-pipe-append (>>) into a notes file. Use this whenever you are about to write to a durable notes/state file, especially right before a context-compaction checkpoint, when told to "flush state" or "write down anything relevant", or when a live notes file has grown large and needs an archive pass. |
State Hygiene
Durable notes/state files (your CLAUDE.md, state/notes.md, state/TODO.md,
and anything else under state/) are your memory across container resets and
context compactions. They only work if you actually read them before you
change them - writing blind is how history gets silently destroyed or
duplicated.
Before writing to any durable notes file
- Read it first. Never overwrite or append to a notes/state file based on memory or assumption of its current contents - the file may have moved on since your last read (another turn, another agent touched shared space, a prior session ended mid-edit). Read (or re-read the relevant section) immediately before editing.
- Never pipe-append. Don't do
echo "..." >> state/notes.md(or equivalent) from a shell command. That's a blind write with no chance to see - and reconcile with - what's already there. Use your file-edit tool (read, then edit/write) instead. - Prefer a targeted edit over a full rewrite for anything long-lived: an edit is less likely to accidentally clobber unrelated content than regenerating the whole file from your current context.
Keeping a notes file lean
- Split into a live file (only what's currently active/gated/relevant - this is what you re-read every turn, keep it short) and an archive (resolved/closed work, moved out of the hot path, never deleted).
- Archive in dated, per-topic chunks -
YYYY-MM-DD-<topic>.md- not one ever-growing archive blob.lson the archive dir should read like a timeline. - When you finish a piece of work, collapse its entry in the live file to a one-line "done" summary and move the full detail into a new dated archive file.
- A live file well past ~500 lines (or into four figures) is overdue for an archive pass - do it at a natural checkpoint (finishing a task, a context-compaction prompt, or whenever you notice it).
Full convention
The hive-wide version of these rules (read-only reference - don't duplicate
it into your own notes) lives at /knowledge/notes-hygiene.md; read that for
the complete rationale.