agentsmd-optimize

# AGENTS.md / CLAUDE.md Optimize

## Overview

`agentsmd-audit` reports and stops. This skill goes one step further: it audits, proposes a prioritized fix list, and **applies the fixes the user approves** directly to the file. Use it when the user wants the doc improved, not just graded.

The quality bar is the same five patterns + four anti-patterns from `agentsmd-audit`. This skill adds the editing discipline: which files are safe to touch, which regions are off-limits, and how to confirm before writing.

## Operating Contract

Audit first, edit second. This skill modifies high-context files (`CLAUDE.md`, `AGENTS.md`, hooks, settings) — treat every write as gated.

Direct actions:
- Run read-only discovery: `ls` paths, check commands against manifests, measure auto-injected rule volume.
- Produce a scored audit and a prioritized fix list with evidence.
- Apply fixes the user has explicitly approved (or already said "做吧 / apply them" for).

Escalate before:
- Editing a **global** file (`~/.claude/**`, `~/.codex/**`) — it affects every project; confirm scope.
- Editing anything inside a generator's auto-gen markers (`<!-- vibeguard-start/end -->`).
- Creating a referenced-but-missing file whose contents you would have to invent.
- Any edit when the user only asked for an audit.

Evidence-backed pushback: challenge any "fact" in the doc that an `ls` or command check refutes (stale paths, missing references, commands absent from the manifest), and cite the check output before proposing the fix. Never restate the doc's claim as truth without verifying it.

Feedback loop: if the same doc keeps drifting (stale paths recur, rules duplicate the auto-loaded set every audit), promote the root cause — split a too-long file into a short index plus scoped references, and fix an over-injected rule set in generator configuration instead of repeating per-line edits.

## When to Activate

- User says "优化 CLAUDE.md", "优化 AGENTS.md", "帮我改一下 claudemd", "optimize my agent doc", "clean up AGENTS.md".
- Right after an audit, when the user says "做吧 / apply the fixes / 改吧".
- A doc has grown noisy, has stale paths, or duplicates auto-loaded rules.

Do **not** use this to write a brand-new instruction file from an empty repo — that is a separate authoring task, not optimization.

## Step 0 — Disambiguate WHICH file first (do not skip)

The single most common failure is optimizing the wrong file. There are usually several candidates. Before reading content, list them and confirm the target:

| Candidate | Path | Scope |
|-----------|------|-------|
| Repo CLAUDE.md | `<repo>/CLAUDE.md` | this project only |
| Repo AGENTS.md | `<repo>/AGENTS.md` | this project, Codex-facing |
| Nested | `<repo>/**/CLAUDE.md`, `packages/*/AGENTS.md` | subtree |
| Global (Claude) | `~/.claude/CLAUDE.md` | every project |
| Global (Codex) | `~/.codex/AGENTS.md` | every project |

Run `ls` on the likely paths and state which one you will edit. If the user's phrasing is ambiguous ("看看 claudemd"), **ask which** — global vs repo changes have very different blast radius. Only skip the question when the user named the path explicitly.

## Step 1 — Audit (reuse the five patterns)

Score each 0/1/2 with cited line ranges. Record shape first (total lines, headings, tables, code blocks, numbered lists) so structural problems surface before subjective judgment.

| Pattern | Clear (2) means |
|---------|-----------------|
| 1. Progressive disclosure | Top file ≤ 150 lines (excluding auto-gen regions); deeper material behind on-demand references |
| 2. Procedural workflows | ≥1 numbered multi-step workflow per common task |
| 3. Decision tables | Tabular "use X for A, Y for B" for each architectural choice |
| 4. Production code examples | 3–10 line snippets from real source (repo files); global files may substitute good/bad rule examples |
| 5. Domain rules with alternatives | Every "don't X" paired with "use Y" |

Anti-patterns to flag: overexploration trap, documentation-environment noise, stale patterns, mixed declarative+procedural.

## Step 2 — Verify every factual claim before proposing an edit

The doc lies more often than you expect. Before writing any fix:

- **Paths**: `ls` every directory/file the doc references. Stale trees (`application/` that no longer exists) and broken references (`routing-contract.md` missing) are the highest-value fixes.
- **Commands**: cross-check build/test commands against `package.json` / `Makefile` / `Cargo.toml`.
- **Duplication**: if the doc has an auto-loaded rule set (vibeguard, a rules/ dir), measure its real injected size (`wc -l` the loaded files). A 100-line CLAUDE.md riding on 1300 lines of always-injected rules is an environment-noise problem the line count alone hides.
- **Conflicts**: numeric limits that contradict the auto-loaded set (e.g. "≤200 lines" vs U-16 "800 lines") — align them.

Label findings as fact / inference / suggestion. A "stale path" is a fact only after the `ls` confirms it.

## Step 3 — Propose the prioritized fix list

Order by `severity × ease`. Each fix names: pattern/anti-pattern, line range, the smallest change, est. minutes, leverage H/M/L. Present it and get a go-ahead before editing (unless the user already said "apply them").

## Step 4 — Apply, respecting these hard boundaries

- **Auto-generated regions are off-limits.** Anything between `<!-- vibeguard-start -->` / `<!-- vibeguard-end -->` (or similar generator markers) is owned by a setup script. Do not edit it — your change gets overwritten and you'd be fighting the generator. Fix the *source* (the generator's input) or report it separately.
- **High-context files need explicit confirmation (SEC-13).** `CLAUDE.md`, `AGENTS.md`, `.claude/settings*.json`, hooks. Editing global (`~/.claude/…`) versions affects every project — confirm scope before writing. Never silently rewrite.
- **No information loss.** When deduping against an auto-loaded rule, keep whatever the local version has that the canonical one lacks (