Harden CLAUDE.md template for agent compliance#1
Merged
Conversation
The generated CLAUDE.md instructions were being read but not followed by agents in practice. This rewrites the template to be a behavioral contract rather than a reference document: - Mark session start and save sections as MANDATORY in headers - Add install/init fallback instructions (pip install, python -m) - Add self-check rule: "if 3+ tasks done without a save, stop and save" - Make save method platform-adaptive (background agent OR inline) - Separate reference material (tiers, querying) from action items - Add PATH warning to init when CLI is installed but not discoverable Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
- Restore save complete as primary action for finished tasks (P1): The previous version directed agents to log completed work as session_log entries, leaving action_items permanently active in boot briefings. save complete is now the first command shown for task completion. - Use module fallback consistently for init and boot (P2): The recovery flow now mentions python -m sessionanchor as a drop-in replacement for all commands, not just boot. - Reword PATH warning for uvx/pipx users (P2): The warning no longer claims the package is installed when it may have been run via uvx. It now says "not found on PATH" and suggests the runner prefix or python -m fallback. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
When a user asks the agent to work on an unrelated repo mid-session, the agent should not save that work into the current project's memory. Adds an explicit instruction with a concrete example. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
claude_md_section.txttemplate so generated CLAUDE.md instructions are treated as a behavioral contract, not a reference documentinit.pywhen the CLI is installed but not discoverableMotivation
In real usage, agents read the generated CLAUDE.md instructions and then ignore them — completing entire sessions without running
sessionanchor bootor a singlesavecommand. The root cause isn't unclear instructions; it's that the template is structured as passive reference material rather than an active protocol with checkpoints.Changes
Template (
claude_md_section.txt)MANDATORY:— agents scan headers, skim body textpython -m sessionanchorfallback for PATH issuesReference:headersInit (
init.py)shutil.which("sessionanchor")and warns if the CLI isn't on PATHTests (
test_init.py)test_claude_md_has_mandatory_sections— verifies all key elements in generated CLAUDE.mdtest_init_warns_when_cli_not_on_path— monkeypatchesshutil.whichto verify warning outputTest plan
sessionanchor initon a new repo produces the updated CLAUDE.md🤖 Generated with Claude Code