80 lines
4.4 KiB
Markdown
80 lines
4.4 KiB
Markdown
---
|
||
type: plan
|
||
title: "CLAUDE.md budget linter plugin — concept (deterministic hook + exception config + maintenance agent)"
|
||
summary: "Future cc-os plugin concept for keeping CLAUDE.md (and eventually whole AI projects) within deterministic token/size budgets — a hook-driven linter that stays silent in range, escalates to a maintenance agent when out of range, and records user-agreed exceptions in a per-project config so allowed growth stays bounded."
|
||
tags:
|
||
- type/plan
|
||
- tool/claude-code
|
||
- domain/context-engineering
|
||
- project/cc-os
|
||
scope: global
|
||
last_updated: 2026-07-08
|
||
date: 2026-07-08
|
||
related:
|
||
- "[[claude-code-system-prompt-customization-surface]]"
|
||
---
|
||
|
||
# CLAUDE.md budget linter plugin — concept
|
||
|
||
Status: idea only, deliberately out of scope as of 2026-07-08. Revisit after the
|
||
system-prompt-profiles work (`cc-os/docs/plans/system-prompt-profiles-assessment.md`).
|
||
Source discussion: cc-os session 2026-07-08; maintenance philosophy drawn from
|
||
`~/servers/proxmox-hermes/docs/claude-md-maintenance.md`.
|
||
|
||
## Problem
|
||
|
||
- CLAUDE.md degrades silently: bloat, stale facts, and instruction overload collapse rule
|
||
adherence (community guidance: ~100 lines of instruction; adherence degrades uniformly
|
||
past ~150–200 instructions). Measured example: cc-os CLAUDE.md reached ~11k tokens —
|
||
~10x a sane budget — by accreting an implementation-status changelog.
|
||
- Pruning is currently manual and memory-dependent ("review it monthly") — exactly the kind
|
||
of discipline that erodes. Nothing enforces a ceiling, and one "just this once" exception
|
||
becomes unbounded growth because the exception is never quantified.
|
||
- The same failure mode applies project-wide: docs that outgrow progressive disclosure,
|
||
copies instead of pointers, files nobody re-reads.
|
||
|
||
## Goal
|
||
|
||
Deterministic, config-driven enforcement of context budgets — zero AI tokens on the happy
|
||
path — with a human-in-the-loop escalation only when a budget is exceeded. Exceptions are
|
||
explicit, quantified, and re-checked, so agreed growth stays bounded instead of becoming
|
||
the new normal.
|
||
|
||
## How it works (mid-level)
|
||
|
||
1. **Hook → linter.** A SessionStart (or periodic) hook runs a deterministic linter over
|
||
CLAUDE.md. In range → no output, no action, 100% deterministic, no model call.
|
||
2. **Per-project dot-config** (JSON for easy slurping, e.g. `.claude-md-lint.json` or a key
|
||
in an existing `.cc-os/config`): default budget (e.g. 1k tokens), cadence
|
||
(`check_every_days`), and an **exceptions block** — each exception records the agreed
|
||
limit, the specific reason, and who/when agreed (e.g. "allowed 1.2k because X, agreed
|
||
2026-07-08"). The linter checks against the *effective* limit, so an exception raises
|
||
the ceiling without removing it.
|
||
3. **Out of range → maintenance agent.** Only then does an AI step run: it assesses the
|
||
file (stale sections, changelog accretion, copies-vs-pointers, `@`-import opportunities)
|
||
and proposes suggestions to the user.
|
||
4. **User resolves**: accept the pruning suggestions, push back, or codify a new quantified
|
||
exception in the config. Never auto-edit CLAUDE.md — automated writes are the known
|
||
failure mode (noise accumulation, contradictory rules, safety-rule drift).
|
||
5. **Cadence control**: config decides whether the hook checks every session or every N
|
||
days (stamp in a gitignored state dir, same pattern as os-doc-hygiene's `.dochygiene/`).
|
||
|
||
## Possible extension: whole-project checks
|
||
|
||
The same skeleton (deterministic scan → config budgets → agent escalation) generalizes to
|
||
weekly project hygiene: file-size ceilings, progressive-disclosure usage (pointers vs
|
||
inlined copies), stale-doc detection, dead `@`-imports.
|
||
|
||
## Build-time considerations
|
||
|
||
- **Overlap with os-doc-hygiene is significant** — it already does deterministic
|
||
SessionStart reminders, per-project gitignored state, AI-assisted classification, and
|
||
git-safe cleanup for stale/bloated docs. First design question at build time: is this a
|
||
new `os-*` plugin or a CLAUDE.md-specific check + budget-config feature *inside*
|
||
os-doc-hygiene (and/or an os-status check for "CLAUDE.md over budget")?
|
||
- Read `cc-os-plugin-skill-naming-convention.md` before naming anything.
|
||
- Token measurement should be deterministic and cheap (chars/4 heuristic or a local
|
||
tokenizer — pick one and freeze it; the budget is a contract, so the measure can't drift).
|
||
- Eval approach exists: same deterministic-first checker + ladder playbook as the other
|
||
os-* plugins.
|