Claude Code for technical writers: what works and what breaks

Claude Code can turn a Git diff, or your description of a change, into a first draft. Without setup, though, nothing holds that draft to your style guide or term list, and it writes from instructions built for engineering work. Then engineering merges an API change while you are on vacation or deep in another project, and without a maintenance workflow the docs can wait until you get back. EkLine connects repository-change detection, scheduled maintenance, and reviewable docs updates for a team-owned accuracy process.

Most of that is fixable today. Claude Code reads project instructions, path-scoped rules, skills, a custom output style, and hooks. Set up together, they give Claude your reader, your terms, and a lint check after matching successful Write or Edit calls while the hook is enabled. Features such as scheduled tasks (formerly routines), Code Review, and shared project instructions partly close each of the old capability gaps. What they leave in place is a dependency on one person: auto-memory corrections stay on one machine unless promoted into shared files, scheduled tasks run as one person's account, and Claude's own review never blocks a merge.

The full claim review used first-party documentation checked on October 21, 2026. Selected setup instructions were checked again on October 23, 2026. The Claude Code changelog tracks CLI releases; cloud-service behavior is documented separately. These are documentation-based examples, not an end-to-end test in a production repository.

TL;DR

• Name your reader and terms in a short CLAUDE.md; scope docs rules to docs files.
• Add an output style for user-facing pages and an enabled lint hook for successful Write or Edit calls.
• Scheduled tasks run as one person, and Code Review never blocks a merge.
• Stop building your own pipeline when the docs must keep running while you are away.

Why Claude Code writes like an engineer

The engineer voice is the default by design. With no output style selected, Claude uses Claude Code's default software-engineering instructions. Unless you tell it who the reader is, it works from instructions written for engineering work, not for your reader.

Your instructions also compete for attention. Discovered project and ancestor instruction files load at session start, along with the auto-memory index (up to its first 200 lines or 25 KB), but Claude treats them as "context, not enforced configuration." The same page advises keeping each CLAUDE.md under 200 lines, because longer files reduce adherence. Pasting your full style guide in works against you.

So split the work: judgment calls (who the reader is, what a page is for) go in short instructions, and mechanical rules go to something deterministic. Mintlify's Ethan Palm makes the same recommendation in his technical-writing workflow: put checkable conventions in a linter or lifecycle hook rather than spending instruction-file space on them.

Before you start

• Claude Code running in the repository that holds your docs.
• A written style guide and term list.
• Vale configured for your style guide, plus jq, which the hooks guide uses to read the edited file's path.

Each example below is adapted from a documented snippet. Test it in your repository before you rely on it.

Instructions guide Claude. In the diagram, "always runs" means an enabled hook on a matching successful Write or Edit call. It does not include edits made through Bash, disabled hooks, or failed tool calls.

Set up Claude Code for documentation in five steps

1. Write a short CLAUDE.md that names the reader

A project CLAUDE.md lives at ./CLAUDE.md or ./.claude/CLAUDE.md, and its instructions are "shared with your team through version control." Lead with the reader, then terminology, then a pointer to the full guide. Illustrative example: replace the reader, terms, and style-guide path with your own:

# Documentation conventions

## Reader
Write for backend developers who already know HTTP and want to integrate an API.

## Terminology
- Use "API key" and never "API token"

## Style
- Follow docs/style-guide.md for anything not covered here.

2. Scope docs rules to docs files

Rules in .claude/rules/ with a paths field load only when Claude reads or edits a matching file, according to the memory documentation. This keeps unrelated file rules out of the initial context; matching rules still consume context when loaded. Example, adapted from the documented format:

---
paths:
  - "docs/**/*.md"
---

# Docs page rules

- One instruction per numbered step
- Start each step with a verb

3. Package repeat checks as a skill

A skill lives at .claude/skills/terminology-check/SKILL.md. Claude loads it when relevant based on the description, or you run this example with /terminology-check. Commit it so your team gets it too. Example, using the documented minimal format:

---
name: terminology-check
description: Checks a docs page against the term list. Use when a docs page is created or edited.
---

Compare every product term on the page with the Terminology section of CLAUDE.md and list each mismatch with its line.

Plugins are the packaging layer for reusing the same setup across multiple repositories. In an October 8, 2026 Reddit post, u/the-ai-scientist described an ASD-STE100-inspired writing plugin. This is its author's report, not an audit of standards compliance. EkLine's open-source ekline-docs-skills plugin includes style-guide and terminology skills. For more options, see the 10 best Claude skills for documentation, ranked.

4. Add an output style for user-facing docs

A custom output style can put Claude in a writing-assistant role. Save it in .claude/output-styles/. Leave out keep-coding-instructions when Claude won't be doing software engineering in that session. After creating or editing the style file, restart the terminal Claude Code session so it loads the change, then switch with /output-style. Example, using the documented frontmatter:

---
name: User docs
description: Writes and edits pages for the reader named in CLAUDE.md
---

You are editing user-facing documentation. Lead every page with the reader's task.
Explain what a feature changes for the reader before how it is built.

5. Put mechanical rules in a lint hook

Hooks give you "deterministic control: certain actions always happen rather than relying on the LLM to choose to run them." Palm's Vale hook matches successful Write or Edit tool calls. Merge its PostToolUse section into .claude/settings.json; the file must already have valid settings JSON or be created with this object. This baseline does not feed lint failures back to Claude:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "vale \"$(jq -r '.tool_input.file_path // empty')\""
          }
        ]
      }
    ]
  }
}

For a PostToolUse hook, exit code 2 "Shows stderr to Claude; the tool already ran." As published, the hook prints Vale's results to stdout, which Claude does not see. To hand failures to Claude, make the hook command send Vale's diagnostics to stderr and exit 2 only when lint fails; successful lint should exit 0. Either way, the edit is already saved. This matcher does not lint edits made through Bash or another tool, and it is not a CI merge gate.

Four gaps, checked against the current docs

Gap	What the docs show now	What still holds
No lasting style or terminology memory	Project CLAUDE.md shared through git; managed CLAUDE.md deployed by IT/DevOps; path-scoped rules	Memory is advisory; auto memory stays on one machine
No sense of the reader	A custom output style can make Claude a writing assistant	Nothing enforces the style
No review gate	Code Review comments on pull requests; a GitHub Action can run on pull requests	Code Review never blocks a merge
Nothing watching the repo	Scheduled tasks run on a schedule or on merged pull requests	Research preview; each scheduled task belongs to one person's account

What remains is about ownership.

Shared instructions are covered, but what Claude learns from your corrections stays with you. Auto memory, the notes Claude saves from your corrections, "is machine-local," so a term you fix on your laptop is unknown to a teammate's session. A subagent (a helper Claude starts with its own instructions) with memory: project keeps its notes in a folder that is "shareable via version control." That works when someone reviews and commits those notes.

The output style gives Claude a reader, but "nothing enforces it," and subagents other than a fork run their own system prompt, so the style does not reach them. You write the reader in by hand.

Code Review "never approves or blocks the pull request," and is available on Team and Enterprise plans for GitHub only. A REVIEW.md file can add team rules, and /code-review runs locally on any plan. The Claude Code GitHub Action costs GitHub Actions minutes plus API tokens per run (or subscription usage with an OAuth token), and its docs don't describe it as a merge gate.

Scheduled tasks, formerly routines, can trigger on merged pull requests, and Anthropic's own example is a weekly docs-drift task that opens update pull requests. They are in research preview and belong to the individual account that creates them. Their pull requests carry that person's connected GitHub identity.

Where the setup fails, and how to recover

• Instructions fade. Trim CLAUDE.md and move page rules into a path-scoped rule.
• Voice slips inside a subagent. Write the reader into its prompt.
• Lint errors land after the page is saved. To block an action first, the memory docs point to a PreToolUse hook.
• A scheduled task shows green but did nothing useful. The scheduled-tasks page says green reports a session without an infrastructure error, not that the requested work succeeded; GitHub webhook events beyond hourly caps are dropped. Read what it opened.
• A draft reads well and fails when followed. A technical writer posting as cryzinger on Hacker News on August 29, 2026 describes Claude-generated writeups that "fall apart when you actually try to follow the instructions they lay out." Have a developer walk every procedure before it ships.

When Claude Code alone is enough

Claude Code now has project memory, skills, hooks, subagents, a GitHub Action, scheduled tasks, and Code Review, so a writer willing to maintain the setup can build much of a docs workflow themselves. Claude Code alone is a good fit when:

• One writer owns the docs and is around to drive most sessions.
• The docs live in one repository, or a plugin carries the setup across a few.
• Your team already runs a CI linter that can fail a pull request, so you don't need Claude to be the gate.
• You accept research-preview scheduled tasks acting as your account.

If that describes your team, the five steps are a starting setup. Confirm the hook loads, test a clean page and an intentional lint failure, and review its feedback before you rely on it.

The test: does the docs process run without you?

Palm wants to "take a vacation without blocking docs ships for a week and a half." Ask four questions about your setup:

1. If an API change merges while you are out for two weeks, does a docs pull request appear under an identity your team owns?
2. When a teammate corrects a term, does the next session on someone else's machine know about it?
3. Can a docs problem fail a check and block the merge?
4. Who maintains the hooks, rules, and scheduled tasks when you move to another project?

With Claude Code alone, the answers are "with scheduled tasks it runs as you; with the GitHub Action it uses the app and credentials your workflow configures," "only if someone commits it," "not through Code Review," and "you." When two or more of those answers worry you, look at tooling built for shared ownership.

Where EkLine fits

EkLine answers the same four questions for a team, and the writer still decides what ships.

Instructions and skills the whole team edits

In Docs Agent, custom instructions apply to every new session your organization starts after saving them, including new sessions started from GitHub, GitLab, or Slack, and any member can edit them. You set the reader there too. Custom skills are authored once and copied into every new session, run with the slash command shown for the saved skill. According to the EkLine changelog, Docs Agent "remembers context about your repositories and conventions across sessions, so your whole team benefits from shared knowledge."

Watching the repository as a team

With automatic PR review, when a non-draft pull request opens or becomes ready on a selected GitHub repository, EkLine stays silent at low confidence, posts a suggestion at medium, and starts a docs-update flow at high confidence that can create a reviewable docs pull request. Scheduled Agents run templates such as Docs Drift Review and Code Sample Review hourly, daily, weekly, or monthly, and deliver a pull request, a Slack message, or both. According to the changelog, any organization member can create and manage them.

A check that can block the merge

Docs Reviewer runs in CI on GitHub Actions, GitLab CI, and Bitbucket Pipelines. For GitHub Actions, the style-guide enforcement guide describes fail_on_error: true plus a required branch-protection check. There is a current implementation discrepancy: the v6 manifest declares that input, but the v6 entrypoint does not pass it to reviewdog. Do not assume the setting alone blocks merges. In the version you deploy, verify that an intentional finding fails the job, then require that exact status check. GitLab and Bitbucket need their own CI configuration.

Before: an API change merges during your vacation, and the docs wait for you. After: when automatic PR review detects clear impact on a monitored GitHub repository and the update flow completes, a docs pull request is available for your review when you get back. In an EkLine case study, Socure's one technical writer merged 348 documentation updates in seven weeks.

Know the limits: the automatic PR review assessment runs once per pull request, its confidence thresholds are fixed, and linked Jira or Linear tickets are not included.

FAQ

What's the difference between CLAUDE.md and AGENTS.md?

Claude Code v2.1.277 or later can read AGENTS.md as project instructions when no CLAUDE.md, .claude/CLAUDE.md, or CLAUDE.local.md exists in the working directory or its ancestors. When those instruction files exist, the default loads them instead. Import AGENTS.md from CLAUDE.md, or use the Project instructions setting to load both. Direct AGENTS.md support also requires its built-in plugin to remain enabled; the first session after some older-version upgrades can still require an import or a new session.

How do I stop Claude Code from flattening my writing voice?

Name your reader and voice in a short CLAUDE.md, use a custom output style for user-facing pages, and let a lint hook catch mechanical rules. Nothing enforces the style, so review diffs for voice before you merge.

Which Claude Code skills help with docs?

Start with one skill per repeat task, such as a terminology check, in .claude/skills/. Shared options include an ASD-STE100 rule set and EkLine's open-source ekline-docs-skills plugin.

Try it on one repository

To check whether your docs process keeps running without you, request Docs Agent access and test EkLine with one repository and one human reviewer. Docs Agent is on all plans, with access on request through [e-mail].