# Claude Md Architect

> Design, create, extract, or audit CLAUDE.md files and their supporting docs/ folder structure for Claude Code projects. Use this skill whenever the user asks to create a new CLAUDE.md, extract context from a long session into a CLAUDE.md system, audit/refactor an existing CLAUDE.md that has bloated, review whether their CLAUDE.md follows best practices, set up a documentation system for Claude Co…

- **Type:** Skill
- **Install:** `agentstack add skill-trin-zenityx-claude-md-architect-claude-md-architect`
- **Verified:** Pending review
- **Seller:** [trin-zenityx](https://agentstack.voostack.com/s/trin-zenityx)
- **Installs:** 0
- **Category:** [Developer Tools](https://agentstack.voostack.com/c/developer-tools)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [trin-zenityx](https://github.com/trin-zenityx)
- **Source:** https://github.com/trin-zenityx/claude-md-architect
- **Website:** https://zenityxai.com

## Install

```sh
agentstack add skill-trin-zenityx-claude-md-architect-claude-md-architect
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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](https://github.com/trin-zenityx)
- **Source:** [trin-zenityx/claude-md-architect](https://github.com/trin-zenityx/claude-md-architect)
- **License:** MIT
- **Homepage:** https://zenityxai.com

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** yes

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: flagged — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-trin-zenityx-claude-md-architect-claude-md-architect
- Seller: https://agentstack.voostack.com/s/trin-zenityx
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.