Maintenance Strategy

Keep docs, instructions, Skills, Plugins, MCP Resources, and validation loops from drifting.

Key takeaways

Agentic docs decay across many surfaces (README, API docs, AGENTS.md, CLAUDE.md, path rules, Skills, Plugins, MCP Resources, eval sets), each with its own drift signal and check.
Add a CI job that warns when src/app code changes without a matching docs or agent-instruction update.
Define a freshness policy with warn/critical thresholds (for example 90 and 180 days) and a list of files requiring review, while excluding history like ADRs and CHANGELOG.
Prioritize fixes by impact: P0 when an agent reads the wrong rule every task, down to P3 for rarely read internal docs.
Remove stale rules instead of only adding new ones, since rule accumulation bloats startup context.

Agentic documentation decays in more places than ordinary docs. You must maintain README files, API docs, AGENTS.md, CLAUDE.md, path rules, Skills, Plugins, MCP Resources, and eval sets.

What Drifts

Surface	Drift	Check
README/docs	broken links, stale commands	link and command checks
`AGENTS.md`	wrong validation command	package script comparison
`CLAUDE.md`	duplicate or conflicting rules	import and length review
`.claude/rules/`	glob mismatch	path matching test
Skills	outdated procedure	sample smoke test
Plugins	installed version differs	manifest/version check
MCP Resources	stale source data	generated_at, source URL
MCP Tools	missing side-effect docs	schema and approval review

CI Check

name: Docs Sync Check
on:
  pull_request:
    paths:
      - 'src/**'
      - 'app/**'
      - 'docs/**'
      - 'AGENTS.md'
      - 'CLAUDE.md'
      - '.claude/**'
      - '.agents/**'

jobs:
  check-docs:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Check docs need update
        run: |
          SRC_CHANGED=$(git diff --name-only origin/main...HEAD | grep -E '^(src|app)/' || true)
          DOCS_CHANGED=$(git diff --name-only origin/main...HEAD | grep -E '^(docs/|AGENTS.md|CLAUDE.md|\.claude/|\.agents/)' || true)
          if [ -n "$SRC_CHANGED" ] && [ -z "$DOCS_CHANGED" ]; then
            echo "::warning::Code changed without docs or agent instruction update."
          fi

Agent Smoke Tests

List the active project instructions and summarize the validation commands.
Do not modify files.

Use the release-check Skill for the current diff.
List risks and validation commands without editing files.

Freshness Policy

freshness:
  warn_after_days: 90
  critical_after_days: 180
  review_required:
    - AGENTS.md
    - CLAUDE.md
    - .claude/rules/**
    - .agents/skills/**
    - .codex-plugin/plugin.json
    - docs/api/**
  exclude:
    - docs/adr/**
    - CHANGELOG.md

Priority

Priority	Criteria	Action
P0	agent reads wrong rule every task	fix now
P1	API or runbook conflicts with behavior	fix before release
P2	Skill/Plugin is stale but avoidable	schedule
P3	rarely read internal doc	archive or delete

Checklist

Item	Check
each surface has an owner	[ ]
code changes trigger doc checks	[ ]
commands in docs match actual scripts	[ ]
Skills and Plugins have smoke tests	[ ]
MCP Resources have source and freshness	[ ]
stale rules are removed, not just added to	[ ]

Key takeaways

Agentic docs decay across many surfaces (README, API docs, AGENTS.md, CLAUDE.md, path rules, Skills, Plugins, MCP Resources, eval sets), each with its own drift signal and check.
Add a CI job that warns when src/app code changes without a matching docs or agent-instruction update.
Define a freshness policy with warn/critical thresholds (for example 90 and 180 days) and a list of files requiring review, while excluding history like ADRs and CHANGELOG.
Prioritize fixes by impact: P0 when an agent reads the wrong rule every task, down to P3 for rarely read internal docs.
Remove stale rules instead of only adding new ones, since rule accumulation bloats startup context.

Agentic documentation decays in more places than ordinary docs. You must maintain README files, API docs, AGENTS.md, CLAUDE.md, path rules, Skills, Plugins, MCP Resources, and eval sets.

What Drifts

Surface	Drift	Check
README/docs	broken links, stale commands	link and command checks
`AGENTS.md`	wrong validation command	package script comparison
`CLAUDE.md`	duplicate or conflicting rules	import and length review
`.claude/rules/`	glob mismatch	path matching test
Skills	outdated procedure	sample smoke test
Plugins	installed version differs	manifest/version check
MCP Resources	stale source data	generated_at, source URL
MCP Tools	missing side-effect docs	schema and approval review

CI Check

name: Docs Sync Check
on:
  pull_request:
    paths:
      - 'src/**'
      - 'app/**'
      - 'docs/**'
      - 'AGENTS.md'
      - 'CLAUDE.md'
      - '.claude/**'
      - '.agents/**'

jobs:
  check-docs:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Check docs need update
        run: |
          SRC_CHANGED=$(git diff --name-only origin/main...HEAD | grep -E '^(src|app)/' || true)
          DOCS_CHANGED=$(git diff --name-only origin/main...HEAD | grep -E '^(docs/|AGENTS.md|CLAUDE.md|\.claude/|\.agents/)' || true)
          if [ -n "$SRC_CHANGED" ] && [ -z "$DOCS_CHANGED" ]; then
            echo "::warning::Code changed without docs or agent instruction update."
          fi

Agent Smoke Tests

List the active project instructions and summarize the validation commands.
Do not modify files.

Use the release-check Skill for the current diff.
List risks and validation commands without editing files.

Freshness Policy

freshness:
  warn_after_days: 90
  critical_after_days: 180
  review_required:
    - AGENTS.md
    - CLAUDE.md
    - .claude/rules/**
    - .agents/skills/**
    - .codex-plugin/plugin.json
    - docs/api/**
  exclude:
    - docs/adr/**
    - CHANGELOG.md

Priority

Priority	Criteria	Action
P0	agent reads wrong rule every task	fix now
P1	API or runbook conflicts with behavior	fix before release
P2	Skill/Plugin is stale but avoidable	schedule
P3	rarely read internal doc	archive or delete

Checklist

Item	Check
each surface has an owner	[ ]
code changes trigger doc checks	[ ]
commands in docs match actual scripts	[ ]
Skills and Plugins have smoke tests	[ ]
MCP Resources have source and freshness	[ ]
stale rules are removed, not just added to	[ ]

What Drifts

CI Check

Agent Smoke Tests

Freshness Policy

Priority

Checklist

On This Page

Maintenance Strategy

What Drifts

CI Check

Agent Smoke Tests

Freshness Policy

Priority

Checklist

On This Page