Claude Md Architect

CLAUDE.md Architect

A skill for designing CLAUDE.md files and their supporting documentation systems for Claude Code projects. Grounded in Anthropic's official memory docs (code.claude.com/docs/en/memory), HumanLayer's "Writing a good CLAUDE.md" guide, Vercel Engineering's January 2026 AGENTS.md eval (53% → 100% pass rate), Arize AI's prompt-learning SWE-Bench results (+10%), and the ETH Zurich AGENTS.md evaluation (Gloaguen et al., arXiv:2602.11988, ICLR 2026 workshop) — which shows that low-quality context files actively reduce task success and add ~20% inference cost.

Core Mental Model

CLAUDE.md is not documentation — it is the highest-leverage prompt in a Claude Code project. Every line loads into every session's context and competes with the actual task for the model's attention. The single most important question for any content is: "Would removing this cause Claude to make mistakes?" If no, cut it.

Three Foundational Principles

1. Minimum Viable Context — Anthropic targets 200 lines | Refactor — split into docs/ or skills |

Writing Style

• Imperatives > descriptions: "Use named exports" > "We prefer named exports"
• Pair prohibitions with directions: "Never use X; instead, do Y" — never just "Never X"
• Bullets for rules and lists; prose only for WHY framing that needs a sentence
• Code blocks only for literal commands or canonical examples — never long snippets
• Use IMPORTANT sparingly for genuinely critical rules (max 1-2 per file)

Progressive Disclosure Setup

For projects beyond 80 lines of CLAUDE.md content, structure like this:

project-root/
├── CLAUDE.md              # 40-80 lines, orchestrator
├── CLAUDE.local.md        # .gitignored personal overrides
├── docs/
│   ├── architecture.md    # "Read when modifying core modules"
│   ├── decisions.md       # ADR-style log
│   └── gotchas-domain.md  # Domain-specific issues
└── .claude/
    ├── rules/             # Path-scoped rules with YAML frontmatter
    ├── commands/          # Slash commands (verbs)
    └── skills/            # On-demand skills

Key distinction:

• @docs/file.md syntax = loads at startup (saves nothing context-wise)
• Prose pointer like "read X when Y" = just-in-time, saves context
• For most cross-cutting concerns, prose pointer is preferred

Output Quality Bar

After completing any mode, ALL of these must be true:

1. Pruning test: Every line passes "would removing it cause mistakes?"
2. Pointer-not-content: No long inline content; references docs instead
3. Self-test: Have Claude (or simulate) reading only the created files and explaining the project. If it can't, the files are insufficient.
4. Versioning: Suggest user commits to git so changes are tracked.
5. No fabrication: If unsure about something, mark [uncertain] and ask user — never invent.

Communication Style

• Match the user's language (Thai/English/mixed)
• Be direct about what won't work — don't sugar-coat anti-patterns
• For Thai-language users, see references/thai-language-notes.md for known CLI bugs and mixed-language patterns
• Always explain WHY a recommendation matters, citing principle (attention limits, pruning test, etc.) — not just "best practice says so"

When User Disagrees

Some users will push back on minimalism ("but I want to be thorough"). Respond:

1. Acknowledge their goal (thoroughness, safety, completeness)
2. Explain the actual failure mode: HumanLayer research shows that as instructions accumulate, LLM doesn't ignore new ones — it ignores all of them uniformly. More rules = fewer followed rules.
3. Offer a compromise: keep CLAUDE.md lean, move detail to docs/ referenced by prose pointer. They get thoroughness AND adherence.

If they still want a 500-line CLAUDE.md, write it but include a clear note that this is against best practice and explain the tradeoff once. Then respect their decision.

Key Sources (for citing when asked)

• Anthropic official memory docs — https://code.claude.com/docs/en/memory (canonical "target under 200 lines per CLAUDE.md file" rule) and /best-practices (canonical pruning-test phrasing)
• HumanLayer "Writing a good CLAUDE.md" by Kyle Mistele — https://www.humanlayer.dev/blog/writing-a-good-claude-md. Source of the "Claude is (not) an expensive linter" framing and the "instructions are ignored uniformly, not selectively" finding. HumanLayer's own CLAUDE.md is 20% cost increase. Mechanism: low-quality boilerplate dilutes attention from real code signals
• "How Many Instructions Can LLMs Follow at Once?" by Jaroslawicz et al. (arXiv:2507.11538) — IFScale benchmark; even frontier models max out at 68% accuracy at 500 instructions. Use this for the "more rules ≠ more followed rules" argument; don't claim a clean 150–200 threshold (the paper shows a gradient, not a cliff)
• Boris Cherny — Head of Claude Code at Anthropic, source of several production-pattern soundbites (Pragmatic Engineer interview, Lenny's Newsletter)

When citing to a user, be honest about provenance: Anthropic docs are first-party; HumanLayer/Vercel/Arize are community/practitioner; arXiv papers are peer-adjacent academic work. Quote numbers exactly when you have them, paraphrase when you don't, and offer to share the URL.

Source & license

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

• Author: trin-zenityx
• Source: trin-zenityx/claude-md-architect
• License: MIT
• Homepage: https://zenityxai.com

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