CLAUDE.md is technical writing - structure it like it

Vlad Kuzin — Tue, 04 Aug 2026 11:55:19 +0000

Your CLAUDE.md is a documentation set with exactly one reader and no editor. It fails in the four ways unstructured documentation has always failed. It grows without a ceiling. It duplicates itself across files that quietly drift apart. It serves every audience at once. And nobody owns it.

Anthropic states the first failure outright in the Claude Code best-practices guide: "Bloated CLAUDE.md files cause Claude to ignore your actual instructions!" The same page names the pattern — "the over-specified CLAUDE.md", where "Claude ignores half of it because important rules get lost in the noise."

Technical writers spent decades building a discipline around those four failures. Most of the advice circulating about context files is that discipline, rediscovered one blog post at a time.

Your instruction file has a word budget and you are over it

Three teams publish three different ceilings.

Anthropic targets under 200 lines per CLAUDE.md, because "longer files consume more context and reduce adherence." Cursor's rules documentation says "Keep rules under 500 lines" and tells you to "Split large rules into multiple, composable rules." HumanLayer keeps its root CLAUDE.md to "less than sixty lines."

The numbers disagree because they are budgets, not limits. The test that survives the disagreement is the one Anthropic publishes per line: "Would removing this cause Claude to make mistakes?" If not, cut it.

That test has a name. It is the acceptance criterion for a topic in topic-based authoring: one topic, one purpose, bounded scope, nothing that does not serve it. A file describing your directory layout, your dependency list, and your architecture is not one topic. It is a manual. Anthropic's /doctor checkup applies exactly this cut, trimming "content Claude can derive from the codebase, such as directory layouts, dependency lists, and architecture overviews" while keeping "pitfalls, rationale, and conventions that differ from tool defaults."

nico, in the Hacker News thread on "Writing a good Claude.md", put the consequence in practitioner terms: "The more information you have in the file that's not universally applicable to the tasks you have it working on, the more likely it is that Claude will ignore your instructions in the file."

Five files, one truth, zero sync

Augment Code's engineering blog describes the repo you probably have open:

"Open a typical project that's been through a few months of AI-assisted development. You'll find some combination of CLAUDE.md, .cursorrules, copilot-instructions.md, AGENTS.md, and maybe a gemini.md for good measure. Almost the same content in each one. Slowly drifting apart."

Their post reports one developer calling it "confetti in the root directory" and another resorting to symlinks to keep five config files in sync. It is a vendor blog that ends in a product pitch, but the symptom is accurate.

Copying a rule into five files costs nothing on the day you do it. It costs on the day you change the rule in three of them.

Anthropic's own fix is one line, documented as an interoperability tip rather than as what it actually is:

@AGENTS.md

## Claude Code
Use plan mode for changes under `src/billing/`.

"Claude Code reads CLAUDE.md, not AGENTS.md," the memory documentation says. "If your repository already uses AGENTS.md for other coding agents, create a CLAUDE.md that imports it so both tools read the same instructions without duplicating them." When you need nothing Claude-specific, ln -s AGENTS.md CLAUDE.md does the same job.

That is single-sourcing: one canonical file, every other file a reference to it. The rule is already circulating in this feed — hash01's guide to structuring CLAUDE.md states it as "Every fact lives in exactly one file. Everything else links to it." What the technical-writing discipline adds is the name and the machinery. DITA standardized the mechanism as @conref, attributes that "provide mechanisms for reusing content within DITA topics or maps". Technical writers shipped it long before the first coding agent existed. Cursor's documentation reaches the same rule from the other direction, listing "Duplicating what's already in your codebase" as a mistake and telling you to "Point to canonical examples instead of copying code."

What this prevents is not clutter. It is drift. Structured content matters to AI systems for exactly this reason: an agent updates the copy it was shown. The other copies keep looking authoritative. They are now wrong.

Splitting into imports does not save you any context

This is the part most posts on the topic get wrong, and the correction is one sentence of vendor documentation.

Splitting a 600-line CLAUDE.md into six imported files does not reduce your context usage. Anthropic says so in one sentence: splitting into @path imports "helps organization but doesn't reduce context, since imported files load at launch." Imports expand recursively to a maximum depth of four hops. Every hop lands in the context window before you type anything.

Two mechanisms are getting conflated, and technical writing keeps them apart on purpose.

Transclusion assembles content at build time. Every referenced block ends up in the output. Imports are transclusion: good for keeping one canonical copy, useless for shrinking what loads.

Conditional processing filters at delivery time, on metadata. The reader gets the Windows steps or the macOS steps, never both. That is the mechanism that shrinks things, and Claude Code ships it as path-scoped rules:

---
paths:
  - "src/api/**/*.ts"
---
- All API endpoints must include input validation

Rules with a paths: field "only apply when Claude is working with files matching the specified patterns." Rules without one "are loaded unconditionally and apply to all files." Skills work the same way with a different trigger: Anthropic recommends them for "domain knowledge or workflows that are only relevant sometimes."

Use imports to stop duplicating. Use paths: to stop loading.

Nesting means two different things depending on the tool

You are probably running both conventions in one repository, and they resolve the same directory tree differently.

agents.md documents precedence: "Agents automatically read the nearest file in the directory tree, so the closest one takes precedence and every subproject can ship tailored instructions."

Claude Code documents concatenation: "All discovered files are concatenated into context rather than overriding each other," ordered "from the filesystem root down to your working directory."

Those are opposite mental models. Put Use tabs in packages/api/CLAUDE.md, expecting it to override Use spaces at the root. On Claude Code you have overridden nothing. You have written a contradiction and committed it. The docs tell you what happens next: "if two rules contradict each other, Claude may pick one arbitrarily."

Technical writers treat this as an assembly question rather than a rules question. Whether a nested topic replaces its parent or extends it is a property of the map. Both models work. Assuming one while running the other is the failure.

The objection to per-directory files is real, and llbeansandrice raised it in that same thread: the approach "isn't portable to other potential AI tools." Correct. Splitting by directory buys scoping and costs portability. You keep both by splitting on directory and keeping one canonical source per rule, rather than one canonical source per tool.

The failure, its real name, and the mechanism you already have

What you feel	What technical writers call it	What you already have
The file grew until the agent skips half of it	Unbounded topic scope	The 200-line target and the per-line deletion test
Four files with nearly the same rules, quietly diverging	Content drift from duplication	`@AGENTS.md` import, or `ln -s AGENTS.md CLAUDE.md`
Backend rules loading during frontend work	No audience separation	`paths:`-scoped rules in `.claude/rules/`, and skills
Nobody knows which rules are still true	No content ownership	CLAUDE.md edits reviewed in the pull request

Row four is Anthropic's own diagnosis of what happens to per-directory files at scale: "Conventions drift, files go stale, and no one owns the root."

What a technical writer would do to your CLAUDE.md on Monday

Five passes. None of them need a tool.

Delete. Run every line through "would removing this cause a mistake?" Anything the agent derives from the code goes. So does anything written around a model limitation that no longer exists — Anthropic makes this an explicit maintenance step, noting that "a rule that forces single-file refactors can be deleted once the limitation is gone."
Deduplicate. Pick the canonical file; every other context file references it. If you run both conventions, AGENTS.md is the source and CLAUDE.md is the one-line import.
Scope. Any rule that applies to part of the tree becomes a paths:-scoped rule. Any workflow that is only relevant sometimes becomes a skill. What stays in CLAUDE.md is what is true in every session.
Resolve contradictions. Read the files in load order, root first and working directory last, and find the rules that fight. This is the pass everyone skips, and it is the one with the arbitrary-outcome failure attached.
Review it in the PR. Anthropic's guidance is to "treat CLAUDE.md edits like any other documentation change so conventions track the code." A rules file that changes without review is a rules file nobody owns.

Pass 2 hides a harder question: before you rename or delete anything, what else points at it? Documentation tools answer this with where-used tracking. Topicary tracks every topic referencing a component and flags the components nothing references. No context-file tooling does. For CLAUDE.md today the answer is grep -r "@path/to/file" before you touch it.

The part none of this tooling does yet

Rename a file that three CLAUDE.md files import and nothing warns you. Imports resolve four hops deep with no reference check on that graph. There is no inventory of which rules are still load-bearing. There is no orphan detection for the file you split out and stopped importing. There is no way to ask which instructions ever changed a behavior.

This gap is not hypothetical to me. The docs tool I work on runs a validation rules engine. It catches broken component references and undefined variables before publishing. None of that machinery points at CLAUDE.md. Nobody has built it for context files.

What you can do today is a pre-commit check: grep every @ import target and fail the commit when the file does not exist. Fifteen lines of shell, and it catches a failure that silently degrades every session afterward.

One deeper limit is worth naming. CLAUDE.md is advisory. It is "delivered as a user message after the system prompt", and Anthropic is explicit that Claude "treats them as context, not enforced configuration." An instruction that must hold every single time belongs in a hook, not in markdown.

Questions

How long should a CLAUDE.md actually be?
Anthropic targets under 200 lines and states that longer files "consume more context and reduce adherence." Cursor's ceiling for a rules file is 500 lines. HumanLayer keeps its root CLAUDE.md under sixty. The number matters less than the per-line test: a line whose removal would not cause a mistake is costing you context for nothing.

Should I use AGENTS.md or CLAUDE.md?
Use AGENTS.md as the source and have CLAUDE.md import it, because Claude Code reads CLAUDE.md and does not read AGENTS.md. A CLAUDE.md containing @AGENTS.md gives both tools the same instructions from one file. ln -s AGENTS.md CLAUDE.md covers the case where you need nothing Claude-specific. The agents.md site reports the convention in use across more than 60,000 open-source projects.

Is this not just prompt engineering?
No, and the difference is practical. Prompt engineering optimizes one message for one response. This is maintenance: four files, hundreds of sessions, months of edits, and no build step that catches a rule which stopped being true in March. Duplication, scope creep, and drift are documentation problems, and they have documentation solutions.

Open your CLAUDE.md and run the deletion test on every line. Then read what is left in load order and find the two rules that contradict each other. That is a documentation review, and you are the technical writer now.

Sources

All accessed 2026-08-04.

Anthropic, Claude Code best practices
Anthropic, How Claude remembers your project
Anthropic, Set up Claude Code in a monorepo or large codebase
AGENTS.md
Cursor, Rules
HumanLayer, Writing a good Claude.md
Augment Code, Your agent's context is a junk drawer
Hacker News, discussion of "Writing a good Claude.md"
hash01, How to structure CLAUDE.md, Skills and Agents
OASIS, DITA 1.3 specification, 2.4.2.1 Conref overview

Structured authoring without XML - how it works

Vlad Kuzin — Tue, 04 Aug 2026 07:05:16 +0000

What is structured authoring?

Structured authoring means writing content as reusable, semantic building blocks instead of free-form documents. The idea has been around for decades. DITA XML formalized it in the early 2000s. But the tooling has always assumed you are comfortable with XML. If you are new to the concept, start with the guide to what a CCMS is.

Topicary keeps the principles and drops the markup. For the research behind this approach, see what 59 technical writers actually say about XML and structured authoring.

Components: write once, reuse everywhere

A component is a block of content (a warning, a setup step, a compatibility note) that you write once and reference from any topic. When you update the source component, every reference updates automatically.

Creating a component

Select any block in the editor, open the slash command menu, and choose "Save as component." Give it a name, and it is available for insertion anywhere in the project.

Where-used tracking

Every component shows a where-used panel: which topics reference it, in which maps, published to which sites. Before you edit a shared component, you can see the blast radius.

Conditions: one topic, multiple audiences

Conditional content lets you maintain a single topic that serves multiple audiences. Tag blocks with conditions — by product, plan, platform, or custom taxonomy — and filter at publish time.

In-editor preview

Toggle conditions in the editor to see exactly what each audience will see. No build step, no waiting. The filtered view updates instantly.

Variables: change once, propagate everywhere

Product names change. Version numbers increment. URLs move. Variables let you define these once and reference them throughout your content. Update the variable value and every reference updates.

The import path

If you are coming from another tool, Topicary imports your existing content:

Markdown: headings, lists, tables, code blocks, images
DITA: topics, maps, conrefs mapped to components, conditions preserved
MadCap Flare: full project import with TOC, snippets, variables, conditions
Confluence: page trees with macro cleanup
Word: .docx with heading hierarchy preserved
OpenAPI: 3.x specs converted to reference documentation

Drag a file or zip onto the import dialog. Format auto-detected, preview before you commit. To understand why I built Topicary and the gap it fills between enterprise CCMS tools and modern wikis, read the full story.

DEV Community: Vlad Kuzin