Agents write code far faster than humans can read it, and humans' mental models of the codebase keep falling behind. docent upgrades "understanding the code logic of xx" from linear conversational Q&A into a visual, interactive, offline-openable artifact of understanding.
Core purpose: to let a human who has fallen behind build, in about 10 minutes, acorrectmental model of the target code logic. Every formal choice in the report serves this purpose.
When to use
- Use only when the user explicitly invokes
/docent <参数>.Do notauto-trigger this skill in ordinary Q&A ("what does this function return")—just answer those questions directly.
Entry points
/docent <自然语言问题 | 路径>
| Argument form | Handling |
|---|---|
| A file or directory path that exists in the repository | The scope of understanding is that path; skip the locating phase |
| Other text | Treat it as a topic (e.g., "how is the token refreshed after the user logs in"), and have the subagent first locate the relevant code |
| No arguments | First ask the user what they want to understand (AskUserQuestion / request_user_input), and do not guess the scope out of thin air |
Execution model: a single dedicated subagent
The main agent does only three things: parse the arguments, dispatchonededicated subagent, and deliver the result. The entire process of locating → reading through → synthesizing → generating happens inside the subagent.
Why one and not many: understanding is an indivisible cognitive process—the answer to "why does this check in file A exist" is often in file B. Fragmented parallel reading severs cross-file causal chains, assembling "what each file is" but not "why they mesh this way." The subagent's value is not parallelism butisolation: keeping the context consumption of bulk code reading out of the main conversation.
When dispatching, hand the following to the subagent in full: the user's original question or path, the current working directory, the absolute path of the directory containing this skill (hereafter <skill-dir>; the subagent needs to read <skill-dir>/references/design-guidelines.md and <skill-dir>/references/components.mditself), and the language of the current conversation. If the current runtime does not support dispatching subagents, the same process can be completed within the main conversation, but on delivery you must remind the user that this session's context has been consumed by a large amount of code reading.
Subagent workflow
1. Locate (skip this phase for path entry points)
Find relevant code from multiple angles to avoid missing things due to a single search posture:
- Search for topic keywords by file name / directory name
- Search by symbol name (function, class, config key)
- Search by string literal (error text, logs, user-visible copy)
- Search by git history (
git log -S/--grep, to see who recently changed the relevant files)
Consolidate into two lists:Core files(to be read through) andPeripheral files(Record associations only, do not go in depth). When the scope is too large to fit, it is better to narrow the core list than to lower reading quality — trimming must be visible in the "Reading Footprint" section of the report.
2. Read-through
Read the core files along the logical flow (not file order): start from the entry point and follow the call chain and data flow. As you read, keep answering "why does it mesh this way", not just "what is it". Compare against git history to understand key evolutionary milestones.
3. Synthesis: Nine mandatory answers
A qualified report must answer the following nine questions. When the scope is very narrow (e.g. a single small file), individual dimensions may beexplicitly marked "not applicable", but silent omission is forbidden:
- Why it exists— what problem this logic solves
- Entry point and main flow— where the entry point is and how the main flow goes
- Code map— explain the files involved within the directory structure: the layout of the relevant code in the repository, and the role each file plays. Discuss positioning with structure; do not split "which files" and "where" into two sections
- Data flow— how key data / state flows
- Pitfalls and special cases— what non-obvious constraints, pitfalls, and boundary special cases exist
- Adjacent contracts— what it promises externally, whom it depends on, who depends on it; the impact scope of changing it
- Historical evolution— from git history, why it grew into its current form (the motivation of key commits)
- How to verify understanding— focus on describing how a person canend-to-endaccept or personally experience this logic: where to start (run command / entry UI / direct DEBUG method / test account), how to walk the operation path step by step, and what behavior should be observed at each step. List automated tests (which test covers it, how to run them) as supporting evidence, but merely giving a list of test commands does not count as answering this item
- Reading footprint— which files were read, why they were considered relevant, and which may be relevant but were not gone into deeply (including a note on scope trimming). This section is the basis for readers to find "you missed X"
4. Generate the HTML report
No fixed template— the presentation form is designed by you for the current question. First read two references:<skill-dir>/references/design-guidelines.md(design specification) and <skill-dir>/references/components.md(component library usage guide).
Assembly discipline: the final HTML is produced by <skill-dir>/scripts/assemble.sh assembly (fixed assets assets/tokens.css、assets/components.css、assets/renderers.js are injected by the script; the renderer is defined in <head>; inline scripts in the body can call it directly). You generate only three things and hand them to the script: the body fragment, the JSON data for diagrams (written in inline scripts in the body), and the layout CSS customized for this run. It is strictly forbidden to have the model retype asset content character by character; to draw diagrams, write JSON and call the renderer, do not hand-draw SVG coordinates; layout, narrative, and design stance are still customized each time. See components.md for usage and data contracts.
Visualization palette (choose per question; do not use them all):
- Sequence diagram — for a request / call chain
- Flowchart — for branching decision logic
- State diagram — for a state machine
- Comparison table — for configuration priority and differences among multiple implementations
- Collapsible multi-level drill-down — progressive disclosure from overview to detail
- Code snippets with anchors — key code verbatim + explanation
Hard quality constraints(violating any one means unqualified):
- First-screen architecture overview: After the one-sentence conclusion at the start of the report, first provide anarchitecture overview diagram— the modules / files involved and their relationships (a graphical presentation of the "code map"), so the reader first builds a spatial sense before going into process details
- Main flow diagram: The reportat least onestandard software engineering diagram (sequence diagram / flowchart / state diagram, chosen according to the problem) to carry the "entry point and main flow", with anchor points on nodes. Diagrams are the universal language for humans to read logic; pure textual description cannot replace them. When the scope is extremely narrow, the architecture overview and the main flow diagram are allowed to be merged into one
- Anchors: All conclusions about code are accompanied by
文件:行号anchors, traceable to specific locations in the repository - Self-contained offline: Single-file HTML, with zero network requests when opened. Diagrams are drawn with inline SVG or pure HTML/CSS, without introducing script libraries that need to be loaded from the network; fonts use system font stacks or inline resources
- Reading footprint: The mandatory item 9 cannot be omitted; this is the basis for users to correct deviations
- Language: The report body follows the language of the current conversation (except code identifiers and anchors)
- Location: Write to
/tmp(e.g./tmp/docent-<主题slug>.html), not into the project repository
Delivery
After the sub-agent returns, the main agent:
- Automatically opens the report with a browser (on macOS use
open <文件>, on other platforms use the corresponding command) - In the main conversation, provides: the report file path + a text summary (what logic was explained, which core files were read, and what noteworthy findings there are)
Correction loop
The purpose of the "Reading footprint" section is to let users discover positioning deviations. After the user points out "X was missed" or "the direction is wrong": within the same session, re-dispatch a sub-agent to revise (giving it the user feedback and the path of the previous report together), producing an updated report. Do not introduce any cross-session persistent state.
Must Not
- Must not dispatch multiple sub-agents in parallel to read separately — fragmented reading cuts off the causal chain
- Must not write the report or intermediate artifacts into the project repository
- Must not reuse a fixed HTML template — each report is custom-designed according to the problem
- Must not write code conclusions in the report that are not supported by anchors
- Must not silently trim scope — all "not read / not went deep" items must be visible in the Reading footprint section