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.
|