---
name: add-claude-md-style
description: Use when generating or updating CLAUDE.md files — defines what belongs vs. what stays in skills/docs, format rules (JSON for data, markdown for rules/instructions), and line budget. Load before any CLAUDE.md write.
---

# CLAUDE.md Style Guide

Defines content rules for CLAUDE.md files generated by ADD commands (primarily `add.xray` STEP 7). Source: Anthropic official docs (code.claude.com/docs/en/memory).

## When NOT to Use

This skill is **only** for CLAUDE.md files. Do not load when:

- Writing or updating any non-CLAUDE.md doc (about.md, plan.md, README.md, hotfix docs) — use `add-doc-schemas` instead
- Authoring or editing skill files (`SKILL.md`) — use `add-skill-creator` and `add-token-efficiency`
- Updating repository README, web docs, or marketing copy — use `add-saas-copy` or general docs guidance

## Why It Matters

CLAUDE.md is injected into every session as a **user message** (not system prompt). Oversized files:
- Consume context tokens on every request, leaving less room for actual work
- Reduce adherence — more content means less attention per rule
- Duplicate content already in JIT-loaded project-patterns skill

**Official target:** under 200 lines per CLAUDE.md file.

## What Belongs in CLAUDE.md

Facts the AI needs in **every session**, not available elsewhere:

- Architecture hierarchy and dependency rules
- Build/run/test commands
- Critical naming conventions (<10 items)
- Multi-tenancy critical rule (if applicable)
- App entry points
- Reference pointer to where detailed patterns live (JIT loading)

## Format Rules

**Target:** 80-150 lines total.

### JSON = DATA. Markdown = INSTRUCTIONS.

This is the fundamental rule. JSON minified is for **structured data that the agent looks up** (configs, mappings, paths, tech stack). Rules, instructions, orientation, and behavioral guidance use **markdown** (lists, tables, prose).

**Minified JSON — when:**
- Tech stack specs (framework, version, engine)
- Path mappings (package → path)
- Config values (env vars, ports, flags)
- Data lists (entity names, module names, enum names)

**Markdown (lists, tables, prose) — when:**
- Dependency rules ("domain never imports outer")
- Behavioral instructions ("always use X before Y")
- Architecture hierarchy and layer rules
- Naming conventions
- Build/run/test commands
- Any orientation or guidance

### Canonical Example

```markdown
# ❌ WRONG — rule as JSON
{"hierarchy":"domain → backend → workers → apps","rule":"inner never imports outer"}

# ✅ RIGHT — rule as markdown, data as JSON
### Layers
domain → backend/database → workers → apps. Inner never imports outer.

### Packages
{"domain":"@rd/domain","backend":"@rd/backend","database":"@rd/database","workers":"@rd/workers"}
```

Same principle applies to import rules and placement maps: render them as **tables** (behavioral guidance), not JSON objects.

## Section Templates

### Architecture Contract

Rules and constraints the agent must follow. Uses **markdown** (tables, lists, prose).

```markdown
## Architecture Contract

> Dependency hierarchy. Check BEFORE implementing or reviewing.

### Layers
domain → backend/database → workers → apps. Inner never imports outer.

### Import Rules
| Package | Can import |
|---|---|
| domain | nothing |
| backend, database | domain |
| workers | domain, database |
| api | all libs |
| frontend | domain |

### Placement
| What | Where |
|---|---|
| Entities | libs/domain/src/entities |
| Services | libs/backend/src/services |
| Repositories | libs/app-database/src/repositories |
| NestModules | apps/backend/src/api/modules |
```

### Technical Spec

Data the agent looks up. Uses **minified JSON** (one object per line).

```markdown
## Technical Spec
{"pkg":"npm","build":"turbo","lang":"typescript"}
{"backend":{"framework":"NestJS","version":"10","entry":"apps/backend/src/api/main.ts"}}
{"database":{"engine":"PostgreSQL","orm":"Kysely"}}
```

**Do NOT include:** full entity lists, all enum names, all type names, all API routes, all guard names, worker handler names.

### Validation Gates

Auto-derived data block emitted by `add-architecture-discovery`. Maps the 5 universal gate intents (lint, typecheck, test, build, format) to the actual command this project uses. Consumed by `add.plan`, `add.build`, `add.autopilot`, `add.review` to inject and enforce checklist items in `tasks.md`.

Uses **minified JSON** (it's data, not behavior). Only includes gates that actually exist — absence is meaningful. The `format` gate, when present, MUST be a non-mutating check command.

```markdown
## Validation Gates
{"validation_gates":{"lint":"npm run lint","typecheck":"npm run typecheck","test":"npm test","build":"npm run build","format":"npm run format:check"}}
```

Language-agnostic — the keys are intents, the values are the real commands for whatever ecosystem this project uses (Node, Python, .NET, Go, Rust, Ruby, Elixir, Java, etc.). If no gates are detected, omit the section entirely. Do not emit `{"validation_gates":{}}`.

### Implementation Patterns (pointer only)

Instructions for where to find patterns. Uses **markdown**.

```markdown
## Implementation Patterns

Detailed patterns in portable skill. Run `/add.xray` to regenerate.

- Location: `.codeadd/skills/project-patterns/` (backend.md, frontend.md, database.md, worker.md)
- Search: `bash .codeadd/scripts/pattern-search.sh --list` → areas
- Load: `bash .codeadd/scripts/pattern-search.sh <area>` → topics + line ranges
```

## Validation Checklist

Before finalizing any generated CLAUDE.md:

- [ ] Total lines ≤ 150?
- [ ] JSON used ONLY for data; rules/instructions/orientation in markdown (no behavioral guidance inside JSON)?
- [ ] Architecture hierarchy in markdown; import/placement rules as tables (not JSON)?
- [ ] Technical Spec uses compact JSON, one object per line?
- [ ] Validation Gates block present using minified JSON when gates detected; section omitted entirely when none (no empty `{}`); `format` only when non-mutating?
- [ ] Patterns pointer block present at end (as markdown)?
- [ ] No section explaining a single concept in >5 lines?
- [ ] No anti-patterns: full frontend/backend/database patterns, API route lists, component/directory trees, inline code examples, feature/business-flow docs, security implementation details, domain type/struct docs, worker/job-queue details, version-specific dependency lists?

## Cross-references

- `{{skill:add-token-efficiency/SKILL.md}}` — generic compression rules (JSON=data, markdown=instructions)
- `{{skill:add-doc-schemas/SKILL.md}}` — doc generation standards (separate pipeline, not for CLAUDE.md)