CLAUDE.md auto-updater
Analyze the current conversation to identify information worth persisting in CLAUDE.md for future sessions, then propose the edits for approval before writing anything.
What to look for
1. Hard-won lessons
- Debugging sessions that revealed non-obvious causes
- Workarounds for platform or tool limitations
- Anti-patterns discovered through failure
- "The real problem was..." moments
2. New infrastructure
- New services deployed
- New endpoints or URLs
- New file paths or directories
- New credentials or tokens (reference only, never the values)
3. New workflows
- Commands that solve recurring problems
- Multi-step processes that work well
- Integration patterns between systems
4. Updated information
- Changed ports, IPs, or URLs
- New capabilities added to existing systems
- Deprecated or removed features
Analysis process
Scan the conversation for keywords:
- "fixed", "solved", "the issue was", "turns out"
- "deployed", "set up", "configured", "installed"
- "new endpoint", "new service", "new path"
- "doesn't work", "limitation", "workaround"
Categorize findings. Only durable facts belong in CLAUDE.md:
- Hard-won lessons go to the "Hard-won lessons" section
- Infrastructure changes update the relevant section
- New workflows go to the appropriate section
- Transient, session-specific notes do not go in CLAUDE.md (see "What not to persist")
Build the exact diff. Produce a unified diff against the current CLAUDE.md showing the precise lines and sections to be added or changed. This diff is what the user approves, not a summary of it.
Present the diff for approval and write nothing until the user approves.
Output format
Show the exact patch first, then a short summary grouped by category:
## Proposed CLAUDE.md updates
```diff
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ section being changed @@
existing context line
+new durable lesson, infra fact, or workflow
```
Summary of the diff above:
- Hard-won lessons: [one line, if any]
- Infrastructure updates: [one line, if any]
- New workflows: [one line, if any]
Apply this diff? Nothing is written until you approve.
What not to persist
CLAUDE.md is team-shared (checked into git) and advisory: it loads into every session, so it is for durable, infrequently-changing facts, not a running log. Per the project-memory skill, keep these out of CLAUDE.md:
- Transient "what we did today" session summaries
- Anything that changes frequently
- Things Claude learns over time through corrections
Route those to auto memory (~/.claude/projects/<project>/memory/, which Claude maintains on its own) or to a gitignored CLAUDE.local.md for personal notes. Putting them in CLAUDE.md bloats shared context and loads stale per-session facts into future sessions.
Rules
- Never add sensitive values. Reference where a credential is stored; never include the actual token.
- Keep it concise. CLAUDE.md should stay scannable; target under 200 lines.
- Avoid duplication. Check whether the information already exists before adding it.
- Match the existing style. Follow the tone and format of the current file.
- Durable facts only. Persist hard-won lessons, infrastructure facts, and workflows. Session-specific notes belong in auto memory or a gitignored
CLAUDE.local.md, never the committed CLAUDE.md.
1---2name: claude-md-updater3description: Scans the session for lessons and workflows, then proposes scoped CLAUDE.md edits. Use for save this lesson or add to context.4---5
6# CLAUDE.md auto-updater
7
8Analyze the current conversation to identify information worth persisting in CLAUDE.md for future sessions, then propose the edits for approval before writing anything.
9
10## What to look for
11
12### 1. Hard-won lessons
13- Debugging sessions that revealed non-obvious causes
14- Workarounds for platform or tool limitations
15- Anti-patterns discovered through failure
16- "The real problem was..." moments
17
18### 2. New infrastructure
19- New services deployed
20- New endpoints or URLs
21- New file paths or directories
22- New credentials or tokens (reference only, never the values)
23
24### 3. New workflows
25- Commands that solve recurring problems
26- Multi-step processes that work well
27- Integration patterns between systems
28
29### 4. Updated information
30- Changed ports, IPs, or URLs
31- New capabilities added to existing systems
32- Deprecated or removed features
33
34## Analysis process
35
361. **Scan the conversation** for keywords:
37 - "fixed", "solved", "the issue was", "turns out"
38 - "deployed", "set up", "configured", "installed"
39 - "new endpoint", "new service", "new path"
40 - "doesn't work", "limitation", "workaround"
41
422. **Categorize findings.** Only durable facts belong in CLAUDE.md:
43 - Hard-won lessons go to the "Hard-won lessons" section
44 - Infrastructure changes update the relevant section
45 - New workflows go to the appropriate section
46 - Transient, session-specific notes do **not** go in CLAUDE.md (see "What not to persist")
47
483. **Build the exact diff.** Produce a unified diff against the current CLAUDE.md showing the precise lines and sections to be added or changed. This diff is what the user approves, not a summary of it.
49
504. **Present the diff for approval** and write nothing until the user approves.
51
52## Output format
53
54Show the exact patch first, then a short summary grouped by category:
55
56````
57## Proposed CLAUDE.md updates
58
59```diff
60--- a/CLAUDE.md
61+++ b/CLAUDE.md
62@@ section being changed @@
63 existing context line
64+new durable lesson, infra fact, or workflow
65```
66
67Summary of the diff above:
68- Hard-won lessons: [one line, if any]
69- Infrastructure updates: [one line, if any]
70- New workflows: [one line, if any]
71
72Apply this diff? Nothing is written until you approve.
73````
74
75## What not to persist
76
77CLAUDE.md is team-shared (checked into git) and advisory: it loads into every session, so it is for durable, infrequently-changing facts, not a running log. Per the project-memory skill, keep these **out** of CLAUDE.md:
78
79- Transient "what we did today" session summaries
80- Anything that changes frequently
81- Things Claude learns over time through corrections
82
83Route those to **auto memory** (`~/.claude/projects/<project>/memory/`, which Claude maintains on its own) or to a gitignored `CLAUDE.local.md` for personal notes. Putting them in CLAUDE.md bloats shared context and loads stale per-session facts into future sessions.
84
85## Rules
86
871. **Never add sensitive values.** Reference where a credential is stored; never include the actual token.
882. **Keep it concise.** CLAUDE.md should stay scannable; target under 200 lines.
893. **Avoid duplication.** Check whether the information already exists before adding it.
904. **Match the existing style.** Follow the tone and format of the current file.
915. **Durable facts only.** Persist hard-won lessons, infrastructure facts, and workflows. Session-specific notes belong in auto memory or a gitignored `CLAUDE.local.md`, never the committed CLAUDE.md.
jamditis