CLAUDE.md, AGENTS.md and .cursor/rules: why they rot, and what belongs somewhere else

CLAUDE.md, AGENTS.md and .cursor/rules: why they rot, and what belongs somewhere else

By Mike Schreiber

An instruction file can start as a useful checklist and end as an ambiguous project diary. Build commands sit beside yesterday’s blocker. An architectural constraint shares a paragraph with an unreviewed suggestion. A temporary workaround reads like a permanent rule.

The repair is not simply making the file shorter. It is separating stable instructions from changing state, then making authority explicit: what a person decided, what the work demonstrated, and what an agent merely proposed.

Use the following process to clean up an existing file without throwing away useful context. All examples below are hypothetical, not customer stories.

1. Separate instructions from the work log

The files in the title have legitimate instruction roles. Claude reads CLAUDE.md at session start for persistent instructions. Its documentation recommends session-wide facts such as build commands and conventions, with procedures moved to skills and narrowly relevant instructions to scoped rules. Claude memory documentation

Cursor describes rules as persistent, reusable context and supports version-controlled .mdc project rules in .cursor/rules. Codex builds its instruction chain at startup. These mechanisms supply guidance; they should not have to double as your changing task ledger. Cursor rules · Codex AGENTS.md guidance

Review each existing entry and assign it a purpose:

| Purpose | Hypothetical entry | Recommended home | | --- | --- | --- | | Stable convention | “Run the billing contract tests before changing invoice serialization.” | Repository instructions | | Scoped instruction | “Billing adapters must preserve upstream error codes.” | Relevant scoped rule | | Human decision | “Keep the old invoice endpoint until the integration owner approves migration.” | Decision record with rationale and scope | | Observed work | “The adapter changed; the contract test failed.” | Session record with evidence | | Proposed note | “The failure may come from timezone conversion.” | Reviewable hypothesis | | Current state | “Next: reproduce the failure using the fixture.” | Handoff or task state |

A decision can justify a durable instruction, but retain its rationale separately. Otherwise, the instruction tells the next person what to do without explaining when it may legitimately change.

2. Remove ambiguity before removing length

Do not impose an arbitrary line limit. Instead, ask whether every instruction has a clear purpose, scope and owner.

Consider this hypothetical line:

Use the old serializer. The replacement is broken. Finish the migration later.

It mixes a directive, an observation and a task. Replace it with separate records:

• Human decision: Keep the existing serializer for the current release, approved by the release owner because compatibility verification is incomplete.
• Observed work: The replacement failed the invoice fixture test in the referenced run.
• Proposed explanation: Timezone conversion may explain the mismatch; not yet verified.
• Next action: Reproduce the mismatch and compare serialized timestamps.
• Review trigger: Revisit the decision after compatibility verification and owner approval.

The repository instruction might then say: “Before replacing invoice serialization, consult the active compatibility decision.” That is more precise than presenting a temporary failure as permanent architecture.

Date entries that can expire, but also give them a review trigger. A date alone does not tell anyone whether an instruction remains valid.

3. Establish authority and ownership

Choose a responsible maintainer for repository instructions. Require changes to explain whether they introduce a convention, narrow its scope, or retire an obsolete rule. This is an editorial workflow recommendation, not a claim that any tool enforces ownership automatically.

Keep evidence distinct from authority. A commit establishes that code changed. A test result establishes what a particular run reported. Neither establishes that a person approved a product tradeoff.

For example, an agent might observe that a hypothetical checkout implementation accepts only one currency. That supports “the implementation currently handles one currency.” It does not support “the business has decided against additional currencies.” Ask the responsible person before recording the latter as a decision.

Apply the same distinction to generated summaries. Read proposed notes as claims to check, not instructions to obey. Preserve unresolved questions instead of converting them into confident rules.

4. Give changing state a session workflow

A useful handoff answers four questions: what happened, what changed, what comes next, and what needs caution. Keep links to evidence near the relevant observation.

If using Hark, its documented session flow is to read the brief before work, update relevant records during work, and call end_session when stopping. The guidance separates stable conventions from Current state, journal entries, features and checklist items rather than batching everything into CLAUDE.md. Hark working with agents

A practical sequence is:

1. Read the current brief and identify the active decision and next action.
2. Check whether the repository still matches the handoff.
3. Record observations as work happens, including failed attempts.
4. Submit new interpretations as proposals, not approved decisions.
5. End with a handoff that names unresolved work and its evidence.

Review behavior matters. In Hark’s Standard trust level, agent proposals require review, while repository facts backed by a commit, PR or release are accepted as observed. Relaxed and Autopilot permit additional automatic acceptance, but decisions are never automatically approved. Conflicts with accepted decisions go to review at every level, and automatically accepted content is labelled “Auto-approved.” Hark trust levels

For the hypothetical serializer task, a failed test can therefore remain observed work while “replace the serializer” remains a proposed decision awaiting human judgment.

5. Make the handoff readable outside the session

Do not confuse a portable brief with transferring a conversation. The goal is to preserve useful decisions and state, not to reproduce every message.

With repository export enabled for a linked repository, Hark commits Current state and the latest session handoff to .hark/HANDOFF.md, accepted decisions to .hark/DECISIONS.md, and an AGENTS.md block. Export writes only accepted content inside the markers and skips unchanged files. The exported brief remains readable when Hark is unreachable. Hark repository export

Treat that export as a readable record, not proof that it contains subsequent activity. Check its freshness before acting, especially after an interrupted session.

For Claude Code, Hark also offers an early-access mod that fetches the brief at session start, restores agreed context after compaction, and drafts a handoff for review when a changed session ends. Its decision guard presents an applicable agreed decision or non-goal before a covered edit, with Allow or Stop choices. These are documented Claude Code mod behaviors, not universal connector behaviors. Hark Claude Code mod

6. Verify the cleanup, then troubleshoot

Start a fresh session and ask for the active constraint, the evidence behind the current blocker, and the next action. A useful answer should distinguish all three rather than merely repeat the instruction file.

Hark’s setup guide suggests verifying a handoff in a fresh session or another client by requesting the project brief and asking it to identify a recorded constraint. That tests retrieval of the constraint, not transfer of chat history. Hark setup from a repository

If something is wrong:

• An obsolete rule still appears: Search maintained instructions and state records for the conflicting statement. Identify its owner and retire or supersede it explicitly.
• A hypothesis appears as policy: Restore its proposed status and ask the decision owner for confirmation.
• The Claude Code mod supplies no brief: Check the configured key, project file and required Claude Code version against the setup instructions. Hark mod troubleshooting
• The decision guard asks too often: Narrow decisions to the relevant area or path, as the mod documentation recommends. Hark mod troubleshooting

Keep privacy boundaries explicit too. The mod sends a handoff summary including file paths, commit subjects, test pass/fail and closing notes, not file contents, diffs, prompts or transcripts. Closing-note cleaning is best effort; a secret written in plain prose could still be sent. Do not put secrets in summaries. Hark mod privacy

FAQs

Should every instruction fit on one screen?

Use scanability as a goal, not a correctness test. Keep necessary conventions and move temporary state elsewhere. Split instructions by purpose rather than deleting essential constraints.

Does a failed test create a decision?

No. It creates an observation to investigate. Choosing to delay a release or preserve an interface requires an explicit decision from the responsible person.

Must changing state live in Hark?

No. A maintained handoff, issue tracker or decision log can serve the workflow. Whatever the home, distinguish observations, proposals and human decisions, and give temporary state an expiry or review trigger.

Sources

• Claude Code: memory
• Cursor: rules
• Codex: AGENTS.md guidance
• Hark: working with agents
• Hark: Claude Code mod
• Hark: setup from your repository