---
name: optimize-claude-md
description: Optimize CLAUDE.md — remove noise (directory trees, type defs, tool tables), keep only commands, constraints, and architecture rules that agents can't discover from code
disable-model-invocation: true
argument-hint: "[path/to/CLAUDE.md]"
allowed-tools: Read, Glob, Grep, Write, Bash
---

# Optimize CLAUDE.md

Based on findings from "Evaluating AGENTS.md" (arXiv:2602.11988): agent instruction files are most effective when they contain only information the agent cannot discover from code itself — build commands, hard constraints, and dependency rules. Verbose files with directory trees, type definitions, and architecture prose actually degrade agent performance.

## Steps

### Step 1 — Locate target file

- If the user provided a path argument, use that.
- Otherwise default to `./CLAUDE.md` (repository root).

### Step 2 — Existence check

- If the file does NOT exist, generate a new minimal CLAUDE.md:
  1. Detect the tech stack (see Step 5).
  2. Read `package.json` scripts / `Makefile` targets / `Cargo.toml` / `pyproject.toml` to extract build/test/lint commands.
  3. Read `tsconfig.json`, `.eslintrc*`, `rustfmt.toml`, etc. for non-obvious compiler/linter constraints.
  4. Write a new CLAUDE.md following the Output Template below.
  5. Show the generated file to the user and ask for confirmation before writing.
  6. Stop here.

### Step 3 — Already minimal?

- Count the lines in the file.
- If the file is **60 lines or fewer**, report: "CLAUDE.md is already minimal (N lines) — no optimization needed." and stop.

### Step 4 — Read context for duplicate detection

- Read `README.md` and `CONTRIBUTING.md` if they exist (first 200 lines each).
- Run `Glob` for `docs/**/*.md` to list available docs (do not read them — just note their existence for dedup).

### Step 5 — Detect tech stack

Detect the primary tech stack by checking for these files (use `Glob`):

| File | Stack |
|------|-------|
| `package.json` | Node.js / JavaScript / TypeScript |
| `Cargo.toml` | Rust |
| `pyproject.toml` or `setup.py` | Python |
| `go.mod` | Go |
| `Makefile` | Make-based build |
| `pom.xml` or `build.gradle*` | Java / JVM |
| `*.sln` or `*.csproj` | .NET / C# |

Read the detected config file(s) to extract commands and constraints.

### Step 6 — Apply KEEP / REMOVE classification

Read the current CLAUDE.md fully, then classify every section and line.

**KEEP** — information agents cannot reliably discover from code:

- Build / test / lint / dev-server commands (exact invocation form)
- Single-test-file execution example
- Non-obvious compiler/linter constraints (ones where the error message alone doesn't make the fix obvious)
- Module-level dependency constraints (what must NOT import what)
- Global / singleton state patterns and initialization order
- Non-obvious conventions (unit system, coordinate system, naming conventions)
- Separate entry-point URLs (one line each)
- Pointers to detailed docs (`docs/` etc.) — one or two lines maximum

**REMOVE** — information agents can discover by reading code or using tools:

- Directory structure / file trees (discoverable via Glob / ls)
- Type definitions, interfaces, enums (readable from source)
- Tool / API / endpoint tables (self-describing)
- Architecture overview prose (doesn't help agents find files faster)
- Implementation details (rendering pipelines, data format descriptions, etc.)
- Content duplicated from README.md or CONTRIBUTING.md
- Listings of files inside docs/ (keep only a pointer like "Detailed specs in `docs/`")
- Badges, logos, decorative formatting

### Step 7 — Generate optimized version

- Produce the optimized CLAUDE.md following the Output Template below.
- **Preserve the original language** of the file. If the original is in Japanese, the output must also be in Japanese. Do not translate.
- If a section would be empty after filtering, omit that section entirely.

### Step 8 — Show diff and ask for confirmation

Present to the user:

1. A **before / after line count** (e.g., "92 lines → 38 lines").
2. The **full unified diff** between the original and optimized versions (use a fenced code block with `diff` syntax highlighting).
3. A **list of removed items** (brief summary of what was cut and why).
4. Ask: "Apply this optimization? (yes/no)"

**Do NOT write the file until the user confirms.**

### Step 9 — Write

After user approval, write the optimized content using the Write tool.

## Output Template

The optimized CLAUDE.md should follow this structure:

```
# CLAUDE.md

## Commands

(All build/test/lint/dev commands with exact invocation. Include a single-test example.)

## [Language/Tool] Constraints

(Non-obvious compiler, linter, or tooling constraints. Omit this section if there are none.)

## Architecture Rules

(Hard dependency constraints, singleton/state patterns, initialization order, conventions like unit systems. Only rules an agent could violate without this guidance.)

## References

(1-2 line pointers to docs/ or other detailed documentation. Omit if not applicable.)
```

## Quality Checks

Before presenting the diff, verify:

1. **Command coverage**: every command from the original CLAUDE.md is preserved in the optimized version (unless it was clearly wrong or obsolete).
2. **Line budget**: aim for 20–60 lines. If the result exceeds 60 lines, look for more content to cut. If under 15 lines, check whether important constraints were lost.
3. **No new content**: do not add information that was not in the original file (except for the section headers from the template).