qt/qtqa/doc_agent_framework/CLAUDE.md

Revision control

++ # CLAUDE.md
++
++ > **For human readers.** You don't load this file manually — Claude
++ > Code auto-loads it when you work in this directory or one below it.
++ > Modify it only when you're changing the framework's harness behavior;
++ > for normal use, treat it as read-only.
++ >
++ > This file coexists with any other `CLAUDE.md` on your machine — your
++ > `~/.claude/CLAUDE.md`, a project-level `CLAUDE.md` in a parent
++ > directory, or anywhere else Claude Code auto-loads. All of them apply
++ > in the same session; nothing here overwrites your own configuration.
++ > If a directive here conflicts with something in your own `CLAUDE.md`,
++ > the closer scope (this file) typically wins because it's more
++ > specific to the current task, but Claude reads all loaded content and
++ > resolves in context.
++
++ ## Resource Priority
++
++ **Always check `~/.claude/` first for skills and agents:**
++ - Skills: `~/.claude/skills/`
++ - Agents: `~/.claude/agents/`
++
++ Load agent definitions from `~/.claude/agents/*.md` when invoking agents
++ with the Task tool.
++
++ ## Role
++
++ The Qt Doc Agent Framework: a generic agentic framework for automating
++ documentation tasks across the pipeline stages (brainstorming, writing,
++ editing, reviewing, publishing). Four pipelines: patch review (A),
++ content creation (B), bug fixing (C), batch maintenance (D). Stage
++ agents ship into `agents/` as each pipeline comes online.
++
++ ## Layer hierarchy
++
++ The framework runs as a four-layer chain. Each layer dispatches to the
++ next; skills never dispatch anywhere.
++
++ ```
++ harness → orchestrator → agent → skill
++ ```
++
++ | Layer | On disk | Role |
++ |-------|---------|------|
++ | Harness | Claude Code + this `CLAUDE.md` | Auto-loaded orientation. Routes framework work to the orchestrator. |
++ | Orchestrator | [`agents/orchestrator.md`](agents/orchestrator.md) | Picks the pipeline (A/B/C/D), gates pre-flight, dispatches stage agents, verifies output. |
++ | Agent | `agents/*.md` | Executes one stage. Loads its own skills. |
++ | Skill | `skills/*/SKILL.md` | Reference material the agent loads on demand. |
++
++ Dispatch capability: the orchestrator has the `Agent` tool; stage agents
++ have it only when marked as fan-out nodes in `agents/README.md`. Default
++ stage behavior is skill-loading, not agent-spawning.
++
++ ## What the harness does
++
++ - Loads this file on session start.
++ - Recognizes framework-shaped requests and hands them to the
++ orchestrator agent.
++ - Passes through direct single-agent invocations when the pipeline is
++ obvious from the request (for example, a bare patch-review request
++ going straight to `qt-doc-reviewer`).
++
++ Everything else (pipeline selection, pre-flight, dispatch mechanics,
++ per-agent verification gates, output-format matrix) lives in the
++ orchestrator layer. See [`agents/orchestrator.md`](agents/orchestrator.md).
++
++ ## Grounding
++
++ Every writing rule the framework relies on is codified as an S-, R-, or
++ T-rule so the agents can cite it in output.
++
++ - **S-sources.** Root style authorities: QUIPs, Qt Writing Guidelines,
++ Microsoft Style Guide.
++ - **R-rules.** Concrete language rules distilled from the S-sources
++ (`skill-language-style`, R1–R64 and beyond).
++ - **T-rules.** AI tells to suppress in generated prose
++ (`skill-ai-tells`, T1–T19, calibrated against 2.4M words of Qt prose).
++
++ Anything not covered by an S / R / T entry is either spelled out for AI
++ use or explicitly excluded.
++
++ ## Deterministic first
++
++ Prefer a deterministic tool over the LLM whenever one can do the job.
++ Deterministic work gives the same result on every run and costs no
++ tokens; route it to a script or tool (grep, Vale, QDoc, ImageMagick,
++ format checkers, `tools/`, the `tests/` harness). Keep the LLM for work
++ that needs judgment: prose review, ambiguity resolution, structural
++ rewrites.
++
++ - Before reading files to find, count, or compare something, run a
++ tool that returns only the answer.
++ - When an agent step is deterministic, the agent calls a tool
++ (Pattern 5) instead of reasoning through it.
++ - When a deterministic check repeats across runs, turn it into a
++ script in `tools/` instead of re-deriving it in each session.
++
++ ## Skill-loading patterns
++
++ The framework uses seven skill-loading patterns. The canonical
++ reference lives at [`doc/loading-patterns.md`](doc/loading-patterns.md);
++ every agent's definition names which patterns it uses.
++
++ ## Environment
++
++ **Qt structure:**
++ - qt5.git super-repo, `dev` branch is the latest unreleased.
++ - Published: doc.qt.io (released), doc-snapshots.qt.io (dev).
++ - Build: `ninja docs` or `ninja html_docs_<Module>`.
++
++ **Key paths:**
++ - QDoc binary: `qtbase/bin/qdoc`
++ - Doc output: `qtbase/doc/`
++ - QDoc source: `qttools/src/qdoc/`
++
++ ## Reference links
++
++ - [Qt Writing Guidelines](https://wiki.qt.io/Qt_Writing_Guidelines)
++ - [Qt Doc Snapshots](https://doc-snapshots.qt.io/qt6-dev/)
++ - [QUIP 21 - Using images in Qt documentation](https://contribute.qt-project.org/quips/21)
++ - [QUIP 25 - Documentation Writing Style](https://contribute.qt-project.org/quips/25)