groove-work-doc

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Chinese

Use $ARGUMENTS as the doc topic if provided.

如果提供了 $ARGUMENTS 则将其作为文档主题。

A structured documentation file explaining how a component, concept, or pattern works — for future agents and humans picking up the codebase.

一份结构化的说明文档，解释某个组件、概念或模式的工作原理，供后续接触代码库的 Agent 和开发人员参考。

Doc file contains:

文档需要包含以下内容：

Sanitize topic for use as filename — strip path separators, special characters, and traversal patterns (
```
../
```
)

Read

memory:

and

specs:

from

.groove/index.md

; resolve docs directory as

<specs>/../docs/

specs:

key is present, otherwise

<memory>/docs/

Ensure the resolved docs directory exists (create if missing)
Research the codebase thoroughly before writing (use Explore agent) — docs should reference actual file paths, not generic descriptions
Interview user if scope is ambiguous: "What's the audience — a new contributor, a future agent, or both?"
Write doc in isolated context (use general-purpose agent)
Verify all four required sections exist before completing
Keep each section concise — this is a reference doc, not a tutorial

Key Files lists actual paths found in the codebase
How It Works traces a real execution path (e.g. "user runs X → Y reads config → Z writes file")
Gotchas surface things that are not obvious from reading the code
Doc does not duplicate what a spec already says — link to the spec if one exists