Claude Md Generator

Self-Healing CLAUDE.md Generator

Users on HN describe re-teaching Claude "how to curl" every morning. Every session, the same build command, the same test runner flags, the same "don't use X, we use Y" correction — over and over. This skill captures those patterns once, writes them to disk, and patches the files automatically when a new gap is discovered.

The output is not a massive documentation dump. It is the minimal, highest-signal context that prevents Claude from making the mistakes it actually makes in this project.

---

SLASH COMMANDS

| Command | Action | | --- | --- | | /scan [path] | Scan a directory tree and extract all detectable patterns | | /generate | Generate a full CLAUDE.md file set from scan results | | /patch "" | Given a mistake description, add the missing entry | | /audit | Read existing CLAUDE.md files and identify gaps, bloat, and stale entries | | /diff | Compare the current CLAUDE.md against what a fresh scan would generate | | /promote | Move a buried subfolder entry up to the root if it's high-frequency | | /demote | Move a root entry to the relevant subfolder to reduce root size | | /trim | Remove entries that haven't prevented a mistake in ≥30 days (with confirmation) | | /explain | Show why a specific entry was added (trace to the originating gap) | | /reset | Regenerate the entire file set from a fresh scan, discarding manual edits | | /completeness | Score context completeness 0–10; show what's missing and how much each gap costs | | /gaps-remaining | Sorted list of remaining context gaps by mistake frequency (highest pain first) | | /drill | Deep-dive one gap category with exhaustive coverage — don't stop at the obvious | | /iterate | Scan → patch → score → repeat until completeness ≥ 8/10 |

---

HIGH-LEVEL WORKFLOW

Trigger: user asks for CLAUDE.md, or Claude just made a mistake
    │
    ├─ Phase 1: Scan
    │     Walk the project tree; extract build, test, conventions, env, gotchas
    │
    ├─ Phase 2: Gap Detection
    │     Compare extracted patterns against existing CLAUDE.md content
    │     Identify what is missing, stale, or mis-placed
    │
    ├─ Phase 3: Structure Planning
    │     Assign each entry to root or a subfolder file
    │     Enforce root ≤50 lines, progressive disclosure rules
    │
    ├─ Phase 4: Generation / Patch
    │     Write new entries; preserve manually written content
    │     Add provenance comments for every generated entry
    │
    ├─ Phase 5: Validation
    │     Verify root line count, no duplicate entries, no dead references
    │     Confirm every subfolder file is reachable from root
    │
    └─ Phase 6: Completeness Score + Next Gap
          Score 0–10; surface the single highest-impact gap still open
          End every session with: "Completeness: X/10. Next gap to close: [gap]."

---

PHASE 1 — SCAN

Walk the project tree and collect evidence for each pattern category. Do not require the user to describe patterns — infer them from the files present.

Pattern Categories

1. Build & Run

Scan for build commands by reading (in order of confidence):

| Source | What to extract | | --- | --- | | package.json → scripts | build, start, dev, preview commands | | Makefile | All targets with short descriptions | | Dockerfile / docker-compose.yml | Service names, port mappings, build args | | Cargo.toml | [profile] settings, workspace members | | pyproject.toml / setup.py | Build backend, entry points | | build.gradle / pom.xml | Main build targets | | .github/workflows/*.yml | CI build steps (authoritative — CI always works) | | justfile | All recipes | | README.md → ## Getting Started section | Manual fallback |

Output: a deduplicated list of : pairs.

2. Test Patterns

| Source | What to extract | | --- | --- | | package.json → scripts.test | Test command and flags | | jest.config.* / vitest.config.* | Test file patterns, timeout, coverage threshold | | pytest.ini / pyproject.toml [tool.pytest] | Test directory, markers, fixture paths | | .github/workflows/ | Test job steps — captures the exact flags CI uses | | Makefile target test | Command CI actually runs | | go.mod presence | Assume go test ./... |

Special attention: extract flags that are always passed (e.g. --run-in-band, -p 1, --no-cache). These are the flags users have to re-explain every session.

3. File & Folder Conventions

| Signal | Pattern to record | | --- | --- | | Consistent casing in filenames | kebab-case, PascalCase, snake_case | | Barrel files (index.ts) in component directories | Export pattern | | Co-located test files (*.test.ts next to source) vs dedicated __tests__/ | Test location rule | | Migration files with timestamp prefix | Naming convention + how to create one | | Feature-flag files | Where they live, how to add one | | Generated files (.generated.ts, *.g.dart) | Do not edit these | | Monorepo structure | Package names and their responsibilities |

4. Environment & Setup

| Source | What to extract | | --- | --- | | .env.example | All required env vars and their purpose | | docker-compose.yml | Local service dependencies (DB, cache, queue) | | README.md → Prerequisites / Installation | Node/Python/Go version requirements | | .nvmrc / .python-version / rust-toolchain | Exact runtime version | | scripts/setup.sh or scripts/bootstrap.sh | One-time setup steps |

5. Architecture & Gotchas

Infer from file structure and naming:

| Signal | Entry to generate | | --- | --- | | src/api/ + src/services/ + src/repositories/ | Three-layer architecture note | | migrations/ present | Never hand-edit migrations; use make migration name=X | | generated/ or __generated__/ directories | Auto-generated — do not edit | | Multiple config files for same tool | Note which one is authoritative | | // @deprecated comments in key files | Flag the deprecated path | | Monorepo with shared packages | Cross-package import rules | | Husky / lint-staged present | Pre-commit hook summary | | .cursorrules or .clinerules already present | Parse these for existing project rules |

---

PHASE 2 — GAP DETECTION

Run after a scan or when the user describes a mistake.

Automated Gap Detection (post-scan)

Compare the scan output against the existing CLAUDE.md content:

1. For each detected pattern, search the existing CLAUDE.md for the key concept.
2. If absent → gap. If present but different → drift (stale entry).
3. Compute a coverage score: patterns_covered / patterns_detected (0–100%).

| Score | Status | | --- | --- | | ≥80% | Well-documented | | 50–79% | Partially documented — gaps exist | | /CLAUDE.md | Package-specific build, test, import rules | | src/api/CLAUDE.md | API layer conventions, auth patterns, error handling | | src/db/CLAUDE.md | Migration commands, ORM patterns, query conventions | | src/components/CLAUDE.md | Component structure, styling conventions, a11y rules | | infra/CLAUDE.md | Terraform/Pulumi commands, environment map, deploy flow | | scripts/CLAUDE.md | What each script does, when to run it | | .github/CLAUDE.md` | CI pipeline structure, how to add a new workflow |

Placement algorithm:

For each new entry:
  1. Does it affect every directory in the project?
     Yes → root, if root has room (

## Test

## Key Conventions
- 
- 
- 

## Gotchas
- 
- 

## Subfolders
- [src/api/](src/api/CLAUDE.md) — 
- [src/db/](src/db/CLAUDE.md) — 
- [packages/](packages/CLAUDE.md) — 

---

PHASE 4 — GENERATION / PATCH

Writing New Files

When generating from scratch:

1. Write the root file first.
2. Write each subfolder file.
3. Add a provenance comment above every generated section:

1. Add an edit instruction at the top of every generated file:

Patching Existing Files

When adding an entry to an existing file:

1. Search the file for the relevant section heading.
2. If the section exists, append the entry under it with a provenance comment.
3. If the section does not exist, add a new section at the bottom.
4. Never delete or reorder manually written content.
5. Never add duplicate entries (check before writing).

Patch entry format:

- Always run `pytest -x --tb=short --timeout=30` — the bare `pytest` command
  hangs on integration tests.

Provenance Tracking

Every generated or patched entry carries a comment:

| Source value | Meaning | | --- | --- | | scan | Detected automatically from project files | | patch | Added after a reported mistake | | manual | Written by the user directly (never overwrite) | | promoted | Moved up from a subfolder via /promote | | demoted | Moved down from root via /demote |

---

PHASE 5 — VALIDATION

Before presenting the output, run these checks:

| Check | Condition | Fix | | --- | --- | --- | | Root line count | Root CLAUDE.md ≤ 50 lines | Move lowest-priority entries to subfolders | | No duplicate entries | No two entries have >80% text overlap | Remove the less-specific one | | No dead subfolder links | Every [subfolder/](subfolder/CLAUDE.md) link resolves | Remove or create the file | | No stale commands | Detected commands match commands referenced in CLAUDE.md | Update diverged entries | | No broken paths | All file paths mentioned exist | Flag with [VERIFY] tag | | Provenance on every entry | Every generated/patched entry has a `` comment | Add missing comments |

Validation Report Format

CLAUDE.MD VALIDATION
────────────────────────────────────────────────────────────
  Root CLAUDE.md        : 34 / 50 lines  [PASS]
  Subfolder files       : 4 files
  Duplicate entries     : 0              [PASS]
  Dead links            : 1              [WARN] src/legacy/CLAUDE.md not found
  Stale commands        : 1              [WARN] build command diverges from Makefile
  Broken paths          : 0              [PASS]
  Entries with no source: 2              [INFO] manually written — preserved
────────────────────────────────────────────────────────────
  Coverage score        : 74%  (partially documented)
  Gaps detected         : 6
  Top gap               : test flags (--timeout, --run-in-band) not documented
────────────────────────────────────────────────────────────

---

COVERAGE SCORING

Run /audit on any project to get:

CLAUDE.MD COVERAGE AUDIT
────────────────────────────────────────────────────────────
  Patterns detected     : 31
  Patterns documented   : 23  (74%)
  ─────────────────────────────────────────────────────────
  DOCUMENTED
    ✓ Primary build command (package.json → scripts.build)
    ✓ Test runner (jest)
    ✓ Node version (.nvmrc → 20.11.0)
    ✓ Docker services (docker-compose.yml → postgres, redis)
    ✓ Migration command (Makefile → make migration)
    … 18 more

  GAPS (8)
    ✗ Test flags  — jest.config.js has testTimeout: 30000 but CLAUDE.md
                    says nothing about timeout
    ✗ Generated files — src/generated/ exists but no "do not edit" note
    ✗ Env var DATABASE_URL — in .env.example but not documented
    ✗ Pre-commit hook — husky installed, no mention in CLAUDE.md
    ✗ Barrel files — src/components/index.ts pattern undocumented
    ✗ Lint command — eslint script in package.json, no entry
    ✗ Feature flag location — src/flags/ detected, no convention note
    ✗ API versioning — src/api/v1/ and src/api/v2/ found, no routing note

  ACTION: run /generate to fill all 8 gaps
────────────────────────────────────────────────────────────

---

SELF-HEALING MECHANISM

The "self-healing" loop works in four steps:

Step 1: Claude makes a mistake in a project with CLAUDE.md
Step 2: User describes the mistake to this skill: /patch "Claude did X, should do Y"
Step 3: Skill extracts the missing entry, assigns it to the right file and section,
        writes the patch with a provenance comment
Step 4: On the next session, Claude reads the patched CLAUDE.md and does not repeat
        the mistake

This is not magic — it is a systematic pipeline from observed error to documented fix. The skill does not auto-commit. Every patch is shown to the user for review before writing. After confirmation, the file is updated in place.

Patch Workflow

User input: /patch "Claude ran npm test instead of make test and it failed"

Skill output:

PATCH PLAN
─────────────────────────────────────────────────────────
  Mistake category : M1 — wrong command
  Missing entry    : Test command is `make test`, not `npm test`
  Target file      : CLAUDE.md (root)
  Target section   : ## Test
  Current content  : (section absent)
  ─────────────────────────────────────────────────────
  PROPOSED PATCH

  ## Test
  
  Always use `make test` — the `npm test` script is a stub that exits 0
  without running anything.

  ─────────────────────────────────────────────────────
  Root after patch : 18 / 50 lines  [PASS]
  Confirm? [yes / no / edit]
─────────────────────────────────────────────────────

---

/diff OUTPUT FORMAT

Shows what a fresh scan would change versus the current CLAUDE.md:

CLAUDE.MD DIFF
────────────────────────────────────────────────────────────
  + ADDITIONS (6 entries the scan found, not in CLAUDE.md)
    + [root] Test: jest --testTimeout=30000 --runInBand
      Source: jest.config.js testTimeout + package.json scripts.test:ci
    + [root] Gotcha: src/generated/ is auto-generated — do not edit
      Source: src/generated/ directory + .gitattributes linguist-generated
    + [src/db/] Migration: make migration name=
      Source: Makefile target 'migration' + migrations/ directory
    + [src/db/] ORM: Prisma — schema at prisma/schema.prisma
      Source: prisma/ directory + package.json dependency
    + [src/api/] Versioning: v1 is deprecated; new endpoints go in v2
      Source: src/api/v1/ has @deprecated JSDoc · src/api/v2/ is active
    + [.github/] CI: push to main triggers deploy-staging; PR only runs tests
      Source: .github/workflows/deploy.yml trigger conditions

  ~ DRIFTED (2 entries that exist but are out of date)
    ~ [root] Build: was `npm run build` → should be `make build`
      Source: package.json scripts.build removed; Makefile build target added
    ~ [root] Node version: was 18 → .nvmrc now specifies 20.11.0

  - REMOVALS (1 entry that no longer applies)
    - [root] Gotcha: avoid src/utils/api.ts (deprecated)
      Source: src/utils/api.ts deleted in codebase

────────────────────────────────────────────────────────────
  Run /generate to apply all changes.  Run /patch for individual entries.

---

MULTI-PACKAGE MONOREPO SUPPORT

For monorepos (detected by presence of packages/, apps/, libs/, or pnpm-workspace.yaml):

File Structure

CLAUDE.md                   ← root: workspace-level only (≤50 lines)
packages/
  CLAUDE.md                 ← package naming, cross-package import rules
  ui/
    CLAUDE.md               ← component conventions, storybook, a11y
  api/
    CLAUDE.md               ← endpoint conventions, auth, error handling
  shared/
    CLAUDE.md               ← what lives here, import rules, change policy
apps/
  web/
    CLAUDE.md               ← next.js specifics, env vars, deploy target
  mobile/
    CLAUDE.md               ← expo/rn specifics, native module notes

Root CLAUDE.md for a monorepo:

# CLAUDE.md

## Workspace
pnpm monorepo. Install: `pnpm install`. Never use `npm` or `yarn`.

## Build
`pnpm build` — builds all packages in dependency order.
`pnpm --filter  build` — builds a single package.

## Test
`pnpm test` — runs all test suites.
`pnpm --filter  test` — single package.

## Key Conventions
- Cross-package imports must go through the package's public index, not deep paths.
- Changes to `packages/shared` affect all consumers — check dependents before merging.

## Subf

…

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [Sandeeprdy1729](https://github.com/Sandeeprdy1729)
- **Source:** [Sandeeprdy1729/claude-design-skill](https://github.com/Sandeeprdy1729/claude-design-skill)
- **License:** Apache-2.0

Install and usage instructions live in the source repository linked above.