CLAUDE.md Patterns & Anti-Patterns

What Belongs in CLAUDE.md

Section Purpose Example

Section	Purpose	Example
Identity	Repo name, Antora component, author, domain	`name: infra-ops`, `component: captures`
Purpose	1-2 sentences — what this repo is	"Lifelong chronicle system and personal knowledge management"
Architecture	Hub-spoke position, deployment pipeline	Pointer to domus-docs aggregator
Blueprint	Directory tree showing the structure	`pages/`, `partials/`, `examples/` layout
Documentation Pattern	Thin wrappers + partials rule	"5+ includes = subdirectory + sub-pages"
Build Commands	`make`, `make serve`, export commands	`make pdf FILE=path/to/file.adoc`
Cross-References	xref syntax for same vs other components	`xref:component::page.adoc[Text]`
Attributes	Pointer to antora.yml — NEVER hardcode	"Check `grep -E '^ [a-z]' antora.yml` before writing"
Remotes	Git remote URLs	origin, gitlab, gitea
Lessons Learned / RCA Log	Real incidents that shaped the rules	RCA-2026-03-19-001: xref resolution
Active Tracks	Brief current focus areas	"RHCSA 9 — Ch 1-2 / 20"

Identity

Repo name, Antora component, author, domain

name: infra-ops, component: captures

Purpose

1-2 sentences — what this repo is

"Lifelong chronicle system and personal knowledge management"

Architecture

Hub-spoke position, deployment pipeline

Pointer to domus-docs aggregator

Blueprint

Directory tree showing the structure

pages/, partials/, examples/ layout

Documentation Pattern

Thin wrappers + partials rule

"5+ includes = subdirectory + sub-pages"

Build Commands

make, make serve, export commands

make pdf FILE=path/to/file.adoc

Cross-References

xref syntax for same vs other components

xref:component::page.adoc[Text]

Attributes

Pointer to antora.yml — NEVER hardcode

"Check grep -E '^ [a-z]' antora.yml before writing"

Remotes

Git remote URLs

origin, gitlab, gitea

Lessons Learned / RCA Log

Real incidents that shaped the rules

RCA-2026-03-19-001: xref resolution

Active Tracks

Brief current focus areas

"RHCSA 9 — Ch 1-2 / 20"

What Does NOT Belong in CLAUDE.md

Anti-Pattern Why It’s Wrong Where It Belongs

Anti-Pattern	Why It’s Wrong	Where It Belongs
Hardcoded IPs	Duplicates antora.yml — guaranteed drift	`antora.yml` attributes
Full infrastructure status tables	Stale within days of writing	`architecture/infrastructure-inventory.adoc` with partials
VM distribution lists	Changes every deployment	`architecture/` or validated designs
HA deployment queues	Active work tracking	Project pages or roadmaps
Security roadmaps	Strategic planning content	`roadmaps/` section
Key IP reference tables	Operational reference	`partials/` (vlan-table, system-inventory)
Detailed command references	Runbook content	Codex pages or runbooks

Hardcoded IPs

Duplicates antora.yml — guaranteed drift

antora.yml attributes

Full infrastructure status tables

Stale within days of writing

architecture/infrastructure-inventory.adoc with partials

VM distribution lists

Changes every deployment

architecture/ or validated designs

HA deployment queues

Active work tracking

Project pages or roadmaps

Security roadmaps

Strategic planning content

roadmaps/ section

Key IP reference tables

Operational reference

partials/ (vlan-table, system-inventory)

Detailed command references

Runbook content

Codex pages or runbooks

The Golden Rule

CLAUDE.md tells Claude how to work in this repo. It does not duplicate the repo’s content.

If information exists in antora.yml, a partial, a validated design, or a runbook — CLAUDE.md should point to it, not copy it.

Maturity Levels

Level	Description	Example
L1: Stub	Repo name + purpose + build command	domus-windows-ops (25 lines)
L2: Functional	+ architecture, cross-refs, attributes guidance	domus-identity-ops (62 lines)
L3: Complete	+ blueprint, patterns, lessons learned, active tracks	domus-captures (441 lines)
L4: Exemplary	+ RCA log, partials system docs, deferred discussions	domus-captures, dots-quantum

Level

Description

Example

L1: Stub

Repo name + purpose + build command

domus-windows-ops (25 lines)

L2: Functional

+ architecture, cross-refs, attributes guidance

domus-identity-ops (62 lines)

L3: Complete

+ blueprint, patterns, lessons learned, active tracks

domus-captures (441 lines)

L4: Exemplary

+ RCA log, partials system docs, deferred discussions

domus-captures, dots-quantum

Template

A good project CLAUDE.md follows this skeleton:

# {repo-name} - Project Context

## Identity
- **Repository:** {name}
- **Component:** `{antora-component}`
- **Author:** {author}
- **Domain:** {url}

## Purpose
{1-2 sentences}

## Hub-Spoke Architecture
{pointer to domus-docs, deployment pipeline}

## Blueprint
{directory tree}

## Documentation Pattern
{thin wrappers + partials rule}

## Build Commands
{make, make serve}

## Cross-References
{xref syntax}

## Attributes
{pointer to antora.yml}

## Remotes
{git remote URLs}

## Lessons Learned
{real incidents}