claude-md-improver

Files (4)

• SKILL.md
• quality-criteria.md · references/
• templates.md · references/
• update-guidelines.md · references/

SKILL.md (first lines)

# CLAUDE.md Improver

Audit, evaluate, and improve CLAUDE.md files across a codebase to ensure PI has optimal project context.

## Workflow

### Phase 1: SuPi Context Baseline Review

**Do not read target instruction files yet.** Start from the session context and available tool surface. When `code_orientation` is available, assume future agents use it routinely and repeatedly—not only as a fallback. Static facts that are on demand rather than automatically injected are still poor CLAUDE.md content when Orientation exposes them directly.

**Purpose:** This baseline is the primary evidence for scoring Criterion 7 (SuPi Context Overlap) in Phase 3. Separate context that arrives on the first turn from facts routinely obtained through Orientation so the audit preserves human reasoning rather than generated inventories.

**Step 1 — Detect SuPi context surfaces.** Scan the conversation context and available tools for:

| Source identifier | What to look for | Typical content |
|-------------------|------------------|-----------------|
| `supi-code-intelligence` overview | Hidden first-turn project overview | Every discovered module's name, description, selected manifest entrypoints, manifest-declared dependency arrows, detected languages |
| `code_orientation` workspace focus | Workspace Orientation | Root manifest, package names and paths, manifest-declared package relationships, direct root files and directories |
| `code_orientation` directory/file focus | Focused Orientation | Applicable instruction files, direct directory entries, package manifest/dependency facts, file outline/import/export observations |
| `native-pi` | Root/ancestor CLAUDE.md or AGENTS.md loaded into the system prompt | Project-wide instructions from the cwd chain |
| Other extensions | `<extension-context source="...">` blocks | Any other extension-delivered context |

**Step 2 — Build the baseline.** Record both first-turn and routine on-demand coverage:

| Source | Content Category | Already Covers | Scope |
|--------|------------------|----------------|-------|
| `supi-code-intelligence` overview | Complete discovered module graph | Module names, descriptions, entrypoints, dependency relationships, languages | **Root-level / first turn** |
| `code_orientation` | Workspace facts | Package paths, manifests, dependency relationships, direct root entries | **Root-level / on demand** |
| `code_orientation` | Directory and file facts | Direct entries, package declarations/dependencies, outlines/imports/exports | **Package-specific / on demand** |
| `code_orientation` | Instruction-file surfacing | Configured `CLAUDE.md`/`AGENTS.md` files for trusted directory focus, up to 200 lines per file | **Package-specific / on demand** |
| `native-pi` | Root instructions | Context files in the cwd/ancestor chain | **Root-level / first turn** |

Add rows for other visible sources. Do not treat an instruction file as redundant merely because `code_orientation` is how its contents reach the model; compare its contents with the other facts Orientation provides.

**Step 3 — Classify redundancy risk by scope.** Assume heavy Orientation use:

- **Root-level high risk** (do NOT recommend for root `./CLAUDE.md`):
  - Package/module inventories, descriptions, entrypoint tables, and manifest dependency graphs
  - Package paths, static project-layout trees, and direct file/directory inventories
  - High-level architecture that adds no ownership, boundary, flow, exception, or rationale

- **Package-specific high risk** (do NOT recommend for that package's instruction file):
  - Direct file/subdirectory listings
  - Package manifest declarations, dependency lists, and manifest-derived relationships
  - Source-symbol inventories that file Orientation exposes without additional reasoning

- **Low risk** (safe to recommend at any scope):
  - Non-obvious commands and workflows (not routine build/test/lint)
  - Gotchas, failure modes, and ordering constraints
  - Ownership, boundaries, initialization/data flow, and exceptions not derivable from manifests
  - Curated "start here" guidance with reasoning
  - Cross-package conventions and project-specific decisions

**Step 4 — Output the baseline.** Produce this structured overview before Phase 2:

```markdown
## Phase 1 Baseline Review

### SuPi Detected: yes / no

### SuPi Context Surfaces

| Source | Delivery | Already Covers | Scope |
|--------|----------|----------------|-------|
| ... | First turn / Routine Orientation | ... | Root / Package-specific |

### Redundancy Risk Assessment

- **Root-level high risk:** [categories]
- **Package-specific high risk:** [categories]
- **Low risk:** [categories]
```

**Note:** If `code_orientation` is available, include its documented workspace/directory/file coverage even before calling it; Phase 2 verifies the actual target outputs.

### Phase 2: Discovery

Now read files from disk. Find all CLAUDE.md files in the repository:

```bash
find . \( -name "CLAUDE.md" -o -name ".claude.md" -o -name ".claude.local.md" \) \
  -not -path "*/.agents/skills/*" -not -path "*/.pi/skills/*" -not -path "*/.claude/skills/*" 2>/dev/null | head -50
```

**Ignore instruction files inside agent skill directories.** Skills may ship `CLAUDE.md`/`AGENTS.md` files as examples, templates, or fixtures. They are skill content, not project instructions — exclude them from discovery, scoring, and updates. Match only hidden agent-tool skill directories such as `.agents/skills`, `.pi/skills`, or `.claude/skills`; do not exclude project directories that happen to be named `skills`.

**File Types & Locations:**

| Type | Location | Purpose |
|------|----------|---------|
| Project root | `./CLAUDE.md` | Primary project context (checked into git, shared with team) |
| Local overrides | `./.claude.local.md` | Personal/local settings (gitignored, not shared) |
| Global defaults | `~/.claude/CLAUDE.md` | User-wide defaults across all projects |
| Package-specific | `./packages/*/CLAUDE.md` | Module-level context in monorepos |
| Subdirectory | Any nested location | Feature/domain-specific context |

**Note:** PI natively loads context files from the cwd and its ancestors. Nested package files are surfaced when `code_orientation` focuses their directories.

After discovery, run workspace `code_orientation` once, then directory Orientation for every target file's containing directory. Use a sufficiently high `maxResults` or narrower repeated focuses so a display cap is not mistaken for absence. This is required baseline evidence, not an optional removal check.

### Phase 3: Quality Assessment

For each CLAUDE.md file found in Phase 2, evaluate against quality criteria, incorporating the Phase 1 baseline review results. See [references/quality-criteria.md](references/quality-criteria.md) for detailed rubrics.

**Quick Assessment Checklist:**

| Criterion | Weight | Check |
|-----------|--------|-------|
| Commands/workflows documented | High | Are non-obvious commands/workflows captured (not routine build/test)? |
| Architecture clarity | High | Can PI understand the codebase structure? |
| Non-obvious patterns | Medium | Are gotchas and quirks documented? |
| Conciseness | Medium | No verbose explanations or obvious info? |
| Currency | High | Does it reflect current codebase state? |
| Actionability | High | Are instructions executable, not vague? |
| SuPi context overlap | Low | Does it duplicate the first-turn overview or facts available through routine `code_orientation` use? **Use the Phase 1 assessment as primary evidence.** |

**Phase 1 enforcement for Criterion 7:**
- Score package-specific files by comparing their contents with the non-instruction sections of directory/file Orientation. Surfacing is the delivery mechanism, not overlap by itself.
- Root- or package-level static facts classified as high risk must be flagged for removal rather than excused as minor overlap.

From mrclrchtr/supi, MIT.

More from mrclrchtr/supi