# Claude Md Architect

> Generate a constraint-first CLAUDE.md (agent operating-rules file) for the current repository by inspecting the project and interviewing the user about the rules that actually matter. Use when the user says "set up CLAUDE.md", "write agent rules for this repo", "claude-md architect", or onboards a new project to Claude Code.

- Skill: `aimasteracc/claude-md-architect` (Agent Skill)
- Install (CLI): `npx skillmds@latest add aimasteracc/claude-md-architect`
- Raw SKILL.md: https://api.skillmd.com/api/skills/aimasteracc/claude-md-architect/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: aimasteracc (https://skillmd.com/u/aimasteracc)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/aimasteracc/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

```markdown
# <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.