Writing docs with Claude Code

Claude Code is Anthropic's CLI agent — runs in your terminal, reads + edits files in your repo, understands long-form project context. It's a natural fit for docs work because docs are text-heavy, MDX is structured enough that an agent can reason about it, and every edit is a diff the writer can review before committing.

This page gives you a paste-ready AGENTS.md + prompt patterns that turn Claude Code into a NookDocs-fluent writing partner. Same bet as NookDocs's core thesis: LLMs get good at docs when you teach them the component language once, not every session.

Install + first run

# Install
npm install -g @anthropic-ai/claude-code

# First run (from your docs repo root)
cd ~/projects/acme-docs
claude

# Claude Code reads AGENTS.md if present + uses it as system context

Claude Code auto-discovers AGENTS.md / CLAUDE.md in the project root. That file becomes the implicit system prompt for every session. Which means: put the NookDocs component rules there, and you never re-paste them.

The AGENTS.md template

Drop this at the root of your docs repo. Claude Code picks it up automatically.

# Project context

This is a NookDocs-based documentation repo. Pages are MDX files
under `docs/`. The config lives at `nookdocs.config.json` (schema:
https://nookdocs.com/schema.json).

## Component library (ALWAYS use, NEVER import)

NookDocs provides a fixed set of components available in every MDX
file. Don't `import` them — they're globally resolved by the
renderer. The full machine-readable spec is at:

  https://nookdocs.com/nookdocs-components.llm.md

Cheat sheet (use these verbatim, don't invent new components):

- Text + structure: `<Callout type="note|info|tip|warning|danger">`,
  `<Note>`, `<Tip>`, `<Warning>`, `<Info>`, `<Danger>`, `<Check>`
- Cards + grids: `<Card title icon href>`, `<CardGroup cols>`,
  `<Tile>`, `<Tiles cols>`, `<HeroCard>`, `<LinkCard>`
- Code: `<CodeGroup>` (wraps multiple fenced code blocks),
  `<CodeBlock>`, `<RequestExample>`, `<ResponseExample>`,
  `<TerminalBlock>`
- Tabs + accordions: `<Tabs>` + `<TabsList>` + `<TabsTrigger>` +
  `<TabsContent>`, `<Accordion>` + `<AccordionGroup>` +
  `<AccordionItem>`
- Steps: `<Steps>` + `<Step title="...">`
- Media: `<Frame caption="...">` (wrap images), `<Image>`, `<Video>`,
  `<Embed>`, `<Mermaid>`
- API fields: `<ParamField path="..." type="..." required default="">`,
  `<ResponseField name="..." type="...">`, `<ApiMethod>`
- Misc: `<Badge>`, `<Banner>`, `<Pill>`, `<Tag>`, `<Kbd>`, `<Icon>`,
  `<Snippet>`, `<Update>`, `<Tooltip>`, `<View>`, `<Visibility>`

## Authoring rules

- Second person, active voice, imperative for instructions.
- Every page has `title` + `description` + `icon` in frontmatter.
- One H1 per page (from the frontmatter title — don't write `# ` in
  the body).
- Use `<ParamField>` for config keys + API request params — always
  with `type` + `required` when applicable + `default` when a default
  exists.
- Code examples in fenced blocks with a language: `​```typescript`,
  `​```bash`, `​```json`, etc.
- Multi-language examples go in `<CodeGroup>`.
- Verb-first H2 headings for how-to sections ("Configure X", not
  "Configuration of X").
- Never write decorative introductions ("In this guide we will...").
  Lead with the answer.
- Cross-link to related pages at the bottom of every page in a
  `## Related` section.

## Audience split (for LLM-friendly content)

Use `<Visibility for="humans">` to wrap UI references, screenshots,
reassurance paragraphs — content that serves browser readers only.

Use `<Visibility for="agents">` to wrap meta-instructions, canonical
URL hints, forbidden-pattern callouts — content for LLMs reading the
page via `/<slug>.md` or `/llms-full.txt`.

## Verification commands

After editing any MDX file:

```bash
# Parse-check (prevents MDX syntax errors on deploy)
node --input-type=module -e "
  import { mdxParse } from 'safe-mdx/parse';
  import { readFileSync } from 'fs';
  mdxParse(readFileSync('docs/PATH.mdx','utf-8'));
" && echo 'parse OK'

# Cross-layer drift (if editing nookdocs.config.json schema keys)
npm run check:sync

# TypeScript
npx tsc --noEmit
```

## When asked to add a new page

1. Pick a path under `docs/` that matches an existing nav section
   (see `nookdocs.config.json#navigation`).
2. Write the MDX file with frontmatter (`title`, `description`,
   `icon`).
3. Add the page to `nookdocs.config.json#navigation` in the right group.
4. Run the parse check.
5. Run `npm run check:sync` if the page documents a config schema key.

## When asked to rewrite a page

1. Read the page in full before editing.
2. Preserve URL-stable section anchors (don't rename H2s that other
   pages link to unless given permission).
3. Apply the authoring rules above.
4. Run the parse check on the result.

Commit this as AGENTS.md at the repo root. Next Claude Code session uses it automatically — no re-paste, no reminder prompts.

Prompt patterns that work

Two patterns produce consistently good output with Claude Code once the AGENTS.md is in place.

Pattern 1: "Audit this page against the guides"

Read docs/guides/style-and-tone.mdx and docs/guides/writing-for-llms.mdx
as reference. Then audit docs/features/search.mdx against those guidelines.
Give me a bulleted list of specific problems — line numbers + what to fix
— not abstract critique.

Produces targeted rewrites. Claude reads the rubric, then the target, returns a changelog not a rewrite. Review + selectively apply.

Pattern 2: "Scaffold a new page like an existing sibling"

Add a new page docs/configuration/webhooks.mdx. Use docs/configuration/
feedback.mdx as the structural template — same frontmatter shape, same
section order, same ParamField usage. Content covers the webhook
delivery configuration: retry policy, signature verification, payload
schema. Commit it + add to nookdocs.config.json nav under Configuration.

Gives Claude a known-good shape to imitate. Results land closer to your house style than a cold-start prompt.

Pattern 3: "Migrate from my current platform"

When your docs come from another tool, tell Claude what the source is — it can detect and convert the structure.

This repo is a Mintlify docs site (docs.json + .mdx files). Convert it to
NookDocs: run `npx nookdocs migrate . -o ../nookdocs-out`, then move the
output into this repo. Resolve the migrate report's "Manual review needed"
items, and make sure every page is wired into the navigation array.

For a source the CLI doesn't convert yet (Docusaurus, GitBook, hand-rolled), Claude can do it by hand — and it can read the source platform's own machine-readable index to learn the page tree:

These are Docusaurus docs (docusaurus.config.js + docs/**). There's no CLI
converter yet, so convert by hand into the flat NookDocs layout: one .mdx per
page at the repo root, map sidebars.js into the navigation array, rewrite
:::note / :::tip admonitions to <Note> / <Tip>, and move static/ to public/.
If the old site is live, read its /llms.txt to confirm the full page list.

The key instruction: NookDocs content is flat at the repo root (contentRoot: "/"), most Mintlify/MDX components keep the same tag name (only <Latex>→<Math> and <Tree>→<FileTree> are renamed), and no page ships without a navigation entry. See Migrating from Mintlify and Migration playbooks.

Workflow — docs as pair programming

Managing long sessions

Claude Code's context window is large (200K+ tokens) but finite. For long docs sessions:

• Work one page at a time. Don't ask Claude to "rewrite the entire section" — rewrite page by page so context stays focused.

• Reference shared context by URL. Instead of pasting the component spec into the prompt, reference the URL: See https://nookdocs.com/nookdocs-components.llm.md for the component list. Claude Code fetches when needed.

• Use /clear between unrelated pages. Starts a fresh session with just the AGENTS.md context. Prevents cross-contamination between tasks.

What Claude Code does well

• Precise MDX edits — targeted changes to specific lines without disturbing surrounding content.

• Frontmatter + nav sync — updating nookdocs.config.json to match a new page location.

• Cross-page consistency — "check if all Configuration pages have the same section order" works reliably.

• Running verification commands — parse check + tsc + check-sync orchestration.

• Commit message composition — follows the project's commit style once it's seen 10+ past commits.

What Claude Code doesn't do well (yet)

• Screenshot + visual design decisions — can't see the rendered output. Keep Claude away from "does this look good" questions; show the rendered page yourself.

• Performance optimisation — bundle size, Core Web Vitals. Not its wheelhouse.

• Inventing product features — if you ask Claude to document a feature that doesn't exist in the codebase, it'll invent plausible-looking nonsense. Verify every claim maps to real shipped behaviour.

• Long-form tutorials from scratch — better at editing than at first-draft 1000-word tutorials. Draft yourself; have Claude polish.

Related

• Writing for LLMs — the broader theory

• Cursor — sibling guide for Cursor-based workflow

• Windsurf — sibling guide for Windsurf

• Component spec — machine-readable component reference

• Schema reference — the nookdocs.config.json field reference

• Human vs agent content — the <Visibility> audience-split story