add-claude-md-style

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.wiki STEP 6). 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 available in the JIT-loaded project wiki

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 (the managed Project Knowledge Base block is ~15 lines and is accounted for within this budget).

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

# ❌ 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).

## 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).

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

## 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":{}}.

Project Knowledge Base (managed block)

Written and owned by /add.wiki STEP 6 — not authored by hand. Delimited by link-reference-definition markers, deliberately NOT HTML comments: the build pipeline strips HTML comments (<!-- -->) from command sources uniformly (the same mechanism that powers feature/plugin injection anchors), so a template using <!-- codeadd-wiki:start --> inside a command source would be destroyed at build time. [//]: # (...) is a link-reference-definition — invisible when rendered, untouched by the build strip, and trivially matched for replace-or-append at runtime.

[//]: # (codeadd-wiki:start)

## Project Knowledge Base

`.codeadd/wiki/` holds this project's patterns, conventions, workflows, and architecture
rationale. Entrypoint: `.codeadd/wiki/index.md`.

- CONSULT BEFORE exploring source for: project conventions, established patterns,
  workflow/how-to questions, architecture rationale ("why is it built this way").
- Do NOT consult for live structural facts (callers, impact, dependencies) — derive those
  from the code graph or the code itself.
- Pages carry `commit` + `sources` frontmatter. If sources changed since (see index.md
  staleness check), verify against code before relying on the page.
- Do not hand-edit generated pages; run /add.wiki update instead. INSTRUCTIONS.md is
  user-owned and steers regeneration.

[//]: # (codeadd-wiki:end)

Replace-or-append semantics: if the markers are found, the block between them is replaced in place; if absent, the block is appended (with a separating blank line). This is /add.wiki's responsibility, not a manual edit.

Legacy cleanup: a CLAUDE.md carrying the old, unmarked "Implementation Patterns" section (pointing at project-patterns/ and pattern-search.sh) predates this mechanism and carries no markers, so replace-or-append cannot remove it automatically. Any updater agent regenerating this file MUST detect and DELETE a legacy "Implementation Patterns" section (or any section referencing project-patterns or pattern-search.sh) before writing the managed block.

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?
• Project Knowledge Base managed block present ([//]: # (codeadd-wiki:start) … [//]: # (codeadd-wiki:end)), and no legacy unmarked "Implementation Patterns" section remains?
• 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)