Auto-Updating CLAUDE.md with Spec Kit: Keep AI Context Accurate

Auto-Updating CLAUDE.md: Keeping AI Context Accurate

CLAUDE.md is Claude’s project memory — the document that gives your AI context about architecture, conventions, and technical decisions. But there is a catch: as a Golang project grows, CLAUDE.md rarely grows with it. Keeping CLAUDE.md up to date automatically with Spec Kit is the difference between an AI that writes idiomatic, consistent Go and one that fights your codebase conventions. Spec Kit closes that gap by extracting patterns and decisions from every feature implementation and folding them back into CLAUDE.md.

This article covers the drift problem, the two update mechanisms Spec Kit offers, and how to keep the whole thing running through configuration, drift detection, and CI.

14.1 The Problem: CLAUDE.md Drift

The failure mode is quiet and cumulative, so it helps to name it precisely. The scenario below shows how a solid CLAUDE.md silently rots over six months of active development.

1Project starts with a solid CLAUDE.md. Six months later:
2  + 12 new features implemented
3  + 3 new patterns emerged in the codebase
4  + 2 new external services integrated
5  + 1 architectural decision changed
6
7CLAUDE.md is still identical to day one.
8Result: Claude Code uses deprecated patterns, is unaware of new
9services, and generates code inconsistent with what already exists.

The takeaway: this is CLAUDE.md drift — one of the biggest long-term risks in SDD. An AI running on stale context does not fail loudly; it quietly produces plausible code that violates conventions you retired months ago.

14.2 Two Update Mechanisms

Spec Kit fixes drift through two complementary commands. The first analyzes a finished feature and proposes additions; the second reconciles CLAUDE.md with the project constitution. The commands below show both.

1# Mechanism 1 — post-implementation update (explicit)
2specify claude-update --feature product-review
3# Analyzes: new files, new patterns, new entities, interface changes
4# → suggests targeted additions to CLAUDE.md · Apply all? [y/n/select]
5
6# Mechanism 2 — constitution sync
7specify claude-sync
8# Ensures constitution.md and CLAUDE.md stay mutually consistent

The distinction matters: claude-update pulls fresh knowledge up from a specific implementation, while claude-sync keeps the high-level principles in constitution.md and CLAUDE.md from contradicting each other. Use the first after every feature and the second whenever your constitution changes.

14.3 Running specify claude-update

The update command does not blindly append text — it analyzes the implementation and presents reviewable suggestions. The session below shows what running it against a finished feature looks like.

 1specify claude-update --feature product-review
 2
 3# 🔄 Analyzing implementation...
 4# ✓ Found 8 new files
 5# ✓ Detected 3 new patterns
 6# ✓ Found 2 new domain entities
 7# ✓ Identified 1 interface change
 8#
 9# Suggested additions to CLAUDE.md:
10# [1] New domain: Review          → "Domain Model" section
11# [2] New pattern: atomic counter → "Patterns" section
12# [3] New dependency: pgx locks   → "Database" section
13#
14# Apply all? [y/n/select]: y

The point: every suggestion is scoped to a section and derived from real artifacts — new files, new entities, decisions recorded in plan.md. You approve, reject, or cherry-pick, so the AI never silently rewrites your memory file.

14.4 CLAUDE.md Before and After

To see the value concretely, compare CLAUDE.md before and after running the update for product-review. The block below shows the “before” — accurate only up to Topic 1.

1# CLAUDE.md — Santekno Shop (before)
2## Domain Model
3- Order: status (PENDING → CONFIRMED → SHIPPED → DELIVERED → CANCELLED)
4- Product: catalog items with stock management
5- User: customer with JWT auth
6
7## Patterns
8- Repository pattern with interface in the domain layer
9- Clean Architecture: handler → usecase → repository → domain

That version says nothing about reviews, ratings, or the atomic-counter pattern the feature introduced. The block below shows the “after” — enriched by specify claude-update.

 1# CLAUDE.md — Santekno Shop (after)
 2## Domain Model
 3- Product: ... + **AverageRating, TotalReviewCount** (added: SHOP-789)
 4- **Review**: rating (1-5) + content + soft delete + purchase verification
 5  - Status: PUBLISHED | DELETED
 6  - Constraint: one review per customer per product (unique index)
 7
 8## Patterns
 9- **Atomic counter update**: UPDATE the aggregate (AverageRating) in the
10  same TX as the entity INSERT — see review_repository.go
11- **Admin-only operation**: usecase checks input.RequestingUserRole == "admin",
12  returns ErrForbidden → handler returns 403
13
14## Implemented Features
15- **Product Review (SHOP-789)**: review and rating system
16  - Spec: .specify/features/product-review/spec.md

The takeaway: the update is specific and actionable — not merely “a Review domain exists,” but how to use it correctly, complete with the ticket that introduced it. That is exactly the level of detail an AI needs to stay consistent.

14.5 Configuring Auto-Update

You decide which sections Spec Kit is allowed to touch. The configuration below separates machine-managed sections from human-owned ones, so auto-updates never clobber hand-written prose.

 1# .speckit-config.yaml
 2claude_md:
 3  file: CLAUDE.md
 4  auto_update_on_implement: false   # manual trigger recommended
 5  managed_sections:
 6    - "Domain Model"
 7    - "Patterns"
 8    - "Database"
 9    - "Implemented Features"
10  protected_sections:
11    - "Project Overview"
12    - "Development Setup"
13    - "Architecture Decision Records"
14  annotate_with_ticket: true        # tag every change with "added: SHOP-###"

The key point: protected_sections is your safety net. Narrative content — project overview, ADRs, setup instructions — is off-limits to the tool, while the factual, extractable sections stay current automatically.

14.6 Drift Detection

You do not have to guess whether CLAUDE.md has fallen behind — Spec Kit can measure it. The command below reports how stale the file is and which sections are most likely outdated.

 1specify audit --claude-drift
 2
 3# CLAUDE.md Drift Analysis
 4# Last update: 2025-06-01 (31 days ago) · 4 features merged since
 5#
 6# HIGH:   Domain Model — Review domain added (SHOP-789) but not in CLAUDE.md
 7# MEDIUM: Patterns — atomic counter used 3× but undocumented
 8# LOW:    Database — 2 new partial indexes not mentioned
 9#
10# Recommendation: specify claude-update --all-features --since "2025-06-01"

The takeaway: drift becomes a visible, ranked report rather than a lurking risk. HIGH findings tell you exactly which stale facts are most likely to mislead the AI on your next session.

14.7 Batch Catch-Up After Many Features

When a project has raced ahead of its documentation — or never used Spec Kit from the start — you can catch up in one pass. The commands below update CLAUDE.md from every feature merged since a given date.

1# Update from all features not yet reflected in CLAUDE.md
2specify claude-update --all-features --since "2025-06-01"
3
4# Or from a specific list
5specify claude-update --features "product-review,cancel-order,flash-sale"

The point: batch mode is how you onboard a legacy project or recover after a busy sprint — you reconcile months of drift into an accurate CLAUDE.md without hand-writing a single entry.

14.8 An Optimal CLAUDE.md Template

The auto-update workflow works best when the file is structured for it from the start. The template below marks each section as managed, partially managed, or protected — a contract the tooling respects.

1# CLAUDE.md — Santekno Shop
2## Project Overview          [Manual — protected]
3## Domain Model              [Managed by Spec Kit — do not edit manually]
4## API Contracts             [Managed by Spec Kit — do not edit manually]
5## Patterns & Conventions    [Managed by Spec Kit — partially manual]
6## Database Schema           [Managed by Spec Kit — partially manual]
7## Testing Guidelines        [Manual — protected]
8## Architecture Decision Records (ADRs)   [Manual — protected]
9## Implemented Features      [Fully managed by Spec Kit]

The takeaway: a clear managed/protected contract prevents the most common accident — hand-editing a managed section only to have it overwritten on the next run. Put your reasoning in protected sections; let the facts live in managed ones.

14.9 Integrating into the Session Workflow

The habit that keeps drift near zero is simple: reconcile before you code. The routine below runs at the start of every Claude Code session.

1# Before starting any new feature implementation:
2specify audit --claude-drift            # check for drift
3specify claude-update --all-features    # catch up if needed
4git add CLAUDE.md && git commit -m "docs: update CLAUDE.md"
5claude                                  # start with accurate context

The point: a two-command pre-flight guarantees Claude opens each session with an accurate model of the project. Committing CLAUDE.md after each update also turns its git history into a running record of how your architecture evolved.

14.10 Automated Health Check in CI

Finally, you can let CI watch CLAUDE.md health on a schedule and file an issue when it slips. The workflow below runs a weekly drift check and opens a ticket automatically.

 1# .github/workflows/claude-md-health.yml
 2name: CLAUDE.md Health Check
 3on:
 4  schedule:
 5    - cron: '0 9 * * MON'   # every Monday morning
 6  workflow_dispatch:
 7jobs:
 8  claude-health:
 9    runs-on: ubuntu-latest
10    steps:
11      - uses: actions/checkout@v4
12      - name: Install Spec Kit
13        run: npm install -g @github/spec-kit
14      - name: Check CLAUDE.md health
15        run: |
16          specify claude-health --output github-summary
17          specify audit --claude-drift --output github-summary
18      - name: Open issue if health is low
19        if: failure()
20        run: gh issue create --title "CLAUDE.md needs update" --body "$(specify claude-health --output markdown)"

The takeaway: with a scheduled check, drift can no longer accumulate unnoticed — the team is nudged every week, and a stale CLAUDE.md becomes a tracked issue instead of a silent quality leak.

14.11 Tips and Gotchas

A few practical rules keep CLAUDE.md effective over the long run:

• Tip — Update before a new session. Reconcile from the previous feature before opening Claude Code for the next one.
• Tip — Add specify claude-update to the PR merge checklist. Make context refresh part of “done.”
• Tip — Review auto-updates before committing. AI extraction can be verbose or occasionally inaccurate; a quick review keeps the file tight.
• Tip — Keep CLAUDE.md under ~1000 lines. Beyond that, split into CLAUDE.md, CLAUDE-patterns.md, CLAUDE-database.md — an overlong file wastes context window and reduces the AI’s effectiveness.
• Gotcha — Configure protected_sections carefully. An unconfigured protected section can be overwritten by the next update.

The bottom line: treat CLAUDE.md as living infrastructure. A little discipline per feature keeps it accurate; neglect lets drift compound until the AI is coding against a project that no longer exists.

14.12 Summary

CLAUDE.md drift is a silent killer in long-running SDD — an AI working from outdated context produces inconsistent code and resurrects patterns you retired.

specify claude-update solves this by extracting patterns, domain-model changes, and architectural decisions from every feature implementation and proposing targeted updates. specify audit --claude-drift and specify claude-health make staleness measurable, and CI can enforce freshness on a schedule.

The mindset shift is the real lesson: CLAUDE.md is a living document, not a write-once file. Keep the managed sections current and the protected sections thoughtful, and Claude Code will keep generating Go that matches your actual conventions.

Next, we look at what to do when the AI ignores the context you so carefully maintained — the debugging workflow for detecting and fixing spec deviation.