Claude Md Architect

claude-md-architect — Build a CLAUDE.md that behaves like a filesystem, not a wish

Purpose

A great agent operating-rules file isn't prose — it's a tight set of constraints and pointers, weighted toward what the agent must NOT do, because that's where autonomous runs go wrong. This skill inspects the repo, extracts the rules implied by how the code is actually written, asks only the questions it can't infer, and writes a focused CLAUDE.md. It optimizes for signal-per-token: every line earns its place in the context window.

How to run

1. Inspect the repo (don't ask what you can read). Detect:
   • language(s), package manager, build/test/lint/format commands (from package.json, pyproject, Makefile, CI config),
   • directory conventions (where source/tests/scripts live),
   • obvious house style (immutability? functional? naming patterns?) from 2–3 representative files,
   • existing CLAUDE.md / .cursorrules / contributing docs to merge, not overwrite.
2. Interview — only the un-inferable. Ask at most 4–6 questions, e.g.:
   • "What must the agent NEVER do here?" (deploy? touch migrations? edit generated files? commit to main?)
   • "What's the definition of done — which command must pass?"
   • "Any landmines — flaky areas, security-sensitive paths, do-not-touch dirs?"
   • "Commit/PR conventions?"
3. Draft the CLAUDE.md using the structure below. Keep it under ~150 lines; link out to long material rather than inlining it.
4. Show it, refine once, write it to ./CLAUDE.md (or merge into the existing one, preserving the user's prior content).

The structure to generate

# <Project> — Agent Operating Rules

## Hard constraints (NEVER)
- <the things that cause real damage — deploy, secrets, force-push, generated files…>

## Definition of done
- <observable condition: e.g. `npm run verify` passes; the page renders>

## Commands
- build: <cmd>   test: <cmd>   lint: <cmd>   format: <cmd>

## House style (what "fits in" looks like here)
- <2–5 concrete, inferred rules — not generic platitudes>

## Layout & landmines
- <where things live; what's fragile; what to read before editing X>

## Workflow
- <branch/commit/PR conventions; when to ask vs proceed>

Principles (why this shape)

• Constraint-first. The NEVER list goes at the top; prohibitions prevent the expensive mistakes a long autonomous run can make.
• Inferred > asked. Anything readable from the repo is stated, not questioned — respect the user's time and avoid re-asking what the code already says.
• Pointers over payloads. Link to deep docs; don't paste them. The file is loaded every session — keep it lean.
• Observable done. "Done" must be a command or a visible state, never a vibe.

Notes

• Never invent constraints. If you can't infer a rule and the user didn't give one, leave it out.
• If a CLAUDE.md already exists, treat it as authoritative and augment it; show a diff.