docs

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Docs

文档

Project memory system. Pick an action:

/docs sync
— Map codebase to references, update roadmap statuses
/docs research
— Discover and formalize what to build next into a roadmap doc
/docs work
— Execute a roadmap item, then update references

Match the first argument to the corresponding section below.

项目记忆系统。选择一项操作：

/docs sync
— 将代码库映射为参考文档，更新路线图状态
/docs research
— 发掘并将下一步要构建的内容规范化为路线图文档
/docs work
— 执行路线图事项，然后更新参考文档

将第一个参数与下方对应的章节匹配。

Core Model

核心模型

```
docs/reference/
```
= what exists in the codebase. Sync writes here.
```
docs/roadmap/
```
= what should exist but doesn't yet. Research writes here. Organized by status.
```
docs/decisions/
```
= decision records. Any command can create these.
```
docs/logs/
```
= chronological work history. Work writes here.

```
docs/reference/
```
= 代码库中已存在的内容。同步操作会写入此目录。
```
docs/roadmap/
```
= 应该存在但尚未实现的内容。研究操作会写入此目录。按状态组织。
```
docs/decisions/
```
= 决策记录。任何命令都可以创建此类文档。
```
docs/logs/
```
= 按时间顺序排列的工作历史。工作操作会写入此目录。

Rule Levels

规则层级

Required — Must be followed.
Recommended — Strong default guidance.

强制要求 — 必须遵守。
推荐遵循 — 强有力的默认指导方针。

Global Rules (required)

全局规则（强制要求）

Command contract — only
```
sync
```
,
```
research
```
,
```
work
```
.
Docs root + folder contract — this skill manages
```
docs/
```
with only these top-level folders:
- ```
docs/reference/
```
- ```
docs/roadmap/
```
- ```
docs/decisions/
```
- ```
docs/logs/
```
- Inside
```
docs/reference/
```
  , use:
  - ```
  features/
```
- ```
architecture/
```
  - ```
  conventions/
```
- ```
runbooks/
```
  - ```
  pitfalls/
```
- Inside
```
docs/roadmap/
```
  , use status folders:
  - ```
  proposed/
```
  — ideas formalized, not started
- ```
in-progress/
```
    — actively being worked on
  - ```
  completed/
```
  — fully shipped
- ```
archived/
```
    — superseded, rejected, or deprioritized

Naming + date rules

```
reference/*
```
→
```
kebab-case.md
```

roadmap/**

decisions/

→

YYYY-MM-DD-kebab-case.md

```
logs/
```
→
```
YYYY-MM.md
```
monthly logs
Dates must be zero-padded ISO 8601:
```
YYYY-MM-DD
```
.

Append-only history — for
```
logs/
```
and
```
decisions/
```
, add new files instead of rewriting history.
Roadmap status lifecycle — track status by moving docs between roadmap folders:
- ```
proposed/
```
  →
```
in-progress/
```
  →
```
completed/
```
- Items that won't be built go to
```
archived/
```
  with a note explaining why (superseded, rejected, deprioritized)
- Every roadmap doc must still have a
```
## Status
```
  line for quick context (e.g.,
```
Proposed
```
  ,
```
In Progress
```
  ,
```
Completed (YYYY-MM-DD)
```
  ,
```
Archived — superseded by [link]
```
  )
Policy files — if
```
AGENTS.md
```
and/or
```
CLAUDE.md
```
exist, keep their docs-memory guidance aligned.
Conflict behavior — if repository conventions conflict with these defaults, do not rewrite conventions silently. Report the mismatch and ask the user before changing direction.

命令约定 — 仅支持
```
sync
```
、
```
research
```
、
```
work
```
三个命令。
文档根目录 + 文件夹约定 — 此Skill管理
```
docs/
```
目录，仅包含以下顶级文件夹：
- ```
docs/reference/
```
- ```
docs/roadmap/
```
- ```
docs/decisions/
```
- ```
docs/logs/
```
- ```
docs/reference/
```
  内部使用以下子文件夹：
  - ```
  features/
```
- ```
architecture/
```
  - ```
  conventions/
```
- ```
runbooks/
```
  - ```
  pitfalls/
```
- ```
docs/roadmap/
```
  内部使用状态文件夹：
  - ```
  proposed/
```
  — 已规范化的想法，尚未启动
- ```
in-progress/
```
    — 正在积极开发中
  - ```
  completed/
```
  — 已完全交付
- ```
archived/
```
    — 已被取代、拒绝或优先级降低
命名 + 日期规则
- ```
reference/*
```
  → 使用
```
kebab-case.md
```
  命名
- ```
roadmap/**
```
  ,
```
decisions/
```
  → 使用
```
YYYY-MM-DD-kebab-case.md
```
  命名
- ```
logs/
```
  → 使用
```
YYYY-MM.md
```
  作为月度日志命名
- 日期必须使用补零的ISO 8601格式：
```
YYYY-MM-DD
```
  。
仅追加历史记录 — 对于
```
logs/
```
和
```
decisions/
```
，添加新文件而非重写历史。
路线图状态生命周期 — 通过在路线图文件夹之间移动文档来跟踪状态：
- ```
proposed/
```
  →
```
in-progress/
```
  →
```
completed/
```
- 不会被构建的事项需移至
```
archived/
```
  ，并附上说明原因的注释（被取代、拒绝或优先级降低）
- 每个路线图文档必须包含
```
## Status
```
  行以提供快速上下文（例如：
```
Proposed
```
  ,
```
In Progress
```
  ,
```
Completed (YYYY-MM-DD)
```
  ,
```
Archived — superseded by [link]
```
  ）
策略文件 — 如果存在
```
AGENTS.md
```
和/或
```
CLAUDE.md
```
，需保持其文档记忆指导方针一致。
冲突处理 — 如果仓库约定与这些默认规则冲突，请勿静默重写约定。需先报告不匹配情况并询问用户后再调整方向。

Global Rules (recommended)

全局规则（推荐遵循）

Prefer focused, single-purpose docs.
Prefer updating existing docs before creating new ones.
Keep docs concrete and scannable.
Treat code as ground truth; avoid full schema dumps in docs.

优先选择聚焦、单一用途的文档。
优先更新现有文档而非创建新文档。
保持文档具体且易于扫描。
将代码视为事实依据；避免在文档中完整转储架构。

sync

Fully map the codebase into

docs/reference/

. Also update roadmap statuses for shipped work.

Completeness requirement: Sync must resolve ALL findings before completing. Do not defer undocumented systems, stale docs, or partial docs to "a future sync." Every implemented system must have a corresponding reference doc when sync finishes. If the scope is large, batch the work — but finish it in this run.

将代码库完整映射到

docs/reference/

中。同时更新已交付工作的路线图状态。

完整性要求：同步操作必须在完成前解决所有发现的问题。不得将未文档化的系统、过时文档或不完整的文档推迟到“未来的同步操作”中。同步完成后，每个已实现的系统都必须有对应的参考文档。如果范围较大，可以分批处理，但必须在本次运行中完成。

1. Ensure structure

1. 确保结构完整性

Runs every sync to keep the folder structure intact. Idempotent — creates what's missing, leaves everything else alone. Never overwrites or removes existing files or folders.

Ensure all folders exist (create any that are missing):

docs/
├── README.md
├── reference/
│   ├── features/
│   ├── architecture/
│   ├── conventions/
│   ├── runbooks/
│   └── pitfalls/
├── roadmap/
│   ├── proposed/
│   ├── in-progress/
│   ├── completed/
│   └── archived/
├── decisions/
└── logs/

If
```
docs/README.md
```
is missing, create it with:
- A short purpose line for
```
docs/
```
- Folder purposes and structure description
- Naming/date/append-only conventions from Global Rules
If
```
AGENTS.md
```
and/or
```
CLAUDE.md
```
exist but lack docs guidance, add a short section:
- ```
docs/
```
  is the project memory system. See
```
docs/README.md
```
  for structure and conventions.
- Update relevant docs when behavior, architecture, or workflows change.

每次同步都会运行此步骤以保持文件夹结构完整。幂等操作——创建缺失的内容，保留现有内容。绝不覆盖或删除现有文件或文件夹。

确保所有文件夹存在（创建任何缺失的文件夹）：

docs/
├── README.md
├── reference/
│   ├── features/
│   ├── architecture/
│   ├── conventions/
│   ├── runbooks/
│   └── pitfalls/
├── roadmap/
│   ├── proposed/
│   ├── in-progress/
│   ├── completed/
│   └── archived/
├── decisions/
└── logs/

如果
```
docs/README.md
```
缺失，创建该文件并包含以下内容：
- ```
docs/
```
  目录的简短用途说明
- 文件夹用途和结构描述
- 全局规则中的命名/日期/仅追加约定
如果存在
```
AGENTS.md
```
和/或
```
CLAUDE.md
```
但缺少文档指导，添加一个简短章节：
- ```
docs/
```
  是项目记忆系统。有关结构和约定，请参阅
```
docs/README.md
```
  。
- 当行为、架构或工作流发生变化时，更新相关文档。

2. Audit docs vs code

2. 审核文档与代码的一致性

Read

docs/README.md

, then review all files under

docs/reference/

docs/roadmap/

docs/decisions/

, and

docs/logs/

Use repository search to check what exists in code (schema, services, routes, UI, jobs, APIs).
Compare every reference doc against current code for accuracy.
Identify implemented systems that have no reference doc.
Check roadmap items — have any been shipped? Should any move between status folders?

阅读

docs/README.md

，然后查看

docs/reference/

docs/roadmap/

docs/decisions/

, 和

docs/logs/

下的所有文件。

使用仓库搜索功能检查代码中存在的内容（架构、服务、路由、UI、任务、API）。
将每个参考文档与当前代码进行比较以确保准确性。
识别没有参考文档的已实现系统。
检查路线图事项——是否有已交付的？是否需要在状态文件夹之间移动？

3. Classify findings

3. 分类发现的问题

Use this taxonomy:

Stale — reference doc is materially incorrect vs current code
Partial — reference doc exists but is missing significant implemented behavior
Undocumented — important implemented system has no reference doc
Roadmap shipped — roadmap item has been implemented and should move to
```
completed/
```

使用以下分类：

过时 — 参考文档与当前代码存在实质性差异
不完整 — 参考文档存在，但缺少重要的已实现行为描述
未文档化 — 重要的已实现系统没有对应的参考文档
路线图已交付 — 路线图事项已实现，需移至
```
completed/
```

4. Sync (required — must resolve ALL findings, no deferral)

4. 同步操作（强制要求——必须解决所有发现的问题，不得推迟）

Resolve every finding discovered in steps 2-3. Do not skip, defer, or deprioritize any item:

Stale docs — update to match current code.
Partial docs — fill in the missing sections from code evidence.
Undocumented systems — create new reference docs (
```
features/
```
,
```
architecture/
```
,
```
conventions/
```
,
```
runbooks/
```
, or
```
pitfalls/
```
as appropriate).
Shipped roadmap items — move the roadmap doc to
```
completed/
```
and update its
```
## Status
```
line.
Add or update
```
conventions/
```
,
```
runbooks/
```
, and
```
pitfalls/
```
entries when repository evidence exists.

If a change would alter repository conventions or policy direction, report the mismatch and ask before making that change.

解决步骤2-3中发现的所有问题。不得跳过、推迟或优先处理任何事项：

过时文档 — 更新以匹配当前代码。
不完整文档 — 根据代码证据补充缺失的章节。
未文档化系统 — 创建新的参考文档（根据情况放入
```
features/
```
,
```
architecture/
```
,
```
conventions/
```
,
```
runbooks/
```
或
```
pitfalls/
```
）。
已交付的路线图事项 — 将路线图文档移至
```
completed/
```
并更新其
```
## Status
```
行。
当仓库存在相关证据时，添加或更新
```
conventions/
```
,
```
runbooks/
```
和
```
pitfalls/
```
中的条目。

如果某项更改会改变仓库约定或政策方向，需先报告不匹配情况并询问用户后再进行更改。

Output Contract (required)

输出约定（强制要求）

When

/docs sync

completes, return all of:

Bootstrap status —
```
created
```
or
```
already present
```
Coverage table with this exact header:

| System | Doc | Status | Action taken |
|--------|-----|--------|--------------|

Summary — counts by status (stale fixed, partial filled, undocumented created, roadmap updated)
Docs changes made — list updated/created/moved paths, or
```
none
```

当

/docs sync

完成时，必须返回以下所有内容：

引导状态 —
```
created
```
（已创建）或
```
already present
```
（已存在）
覆盖范围表格，使用以下精确表头：

| 系统 | 文档 | 状态 | 执行的操作 |
|------|------|------|------------|

摘要 — 按状态统计的数量（已修复的过时文档、已补充的不完整文档、已创建的未文档化系统、已更新的路线图）
文档更改记录 — 列出已更新/创建/移动的路径，或
```
none
```
（无更改）

research

Discover what to build next and formalize it into a roadmap doc.

发掘下一步要构建的内容并将其规范化为路线图文档。

1. Scan for candidates

1. 筛选候选事项

Work through these lenses. Not all will apply to every product — use what's relevant:

Usage and behavior — What are users actually doing?

If analytics tools are available, check usage patterns, funnels, retention, and drop-off points
Identify features that are heavily used (double down) vs unused (cut or rethink)

Demand — What are users asking for?

Check issue trackers, feature request backlogs, and support channels for patterns
Look for frequently requested capabilities or common complaints

Pain — What's broken or frustrating?

Check

docs/reference/pitfalls/

and

docs/reference/runbooks/

for recurring operational pain

Look at bug reports, incident history, and support escalations

Strategy — What's the current direction?

Read
```
docs/roadmap/
```
for existing plans and their statuses
Read
```
docs/reference/features/
```
for gaps, limitations, and natural next steps
Consider business goals and priorities the user has communicated

Landscape — What's happening externally?

Research competitors, adjacent tools, and market shifts if relevant
Identify opportunities others are capitalizing on

Technical opportunity — What does the codebase reveal?

Scan code for
```
TODO
```
,
```
FIXME
```
,
```
HACK
```
, stubs, and dead paths
Identify tech debt that's actively slowing down development

Vision — What's possible that doesn't exist yet?

What adjacent problems could we solve with what we've already built?
What emerging capabilities or trends could we leverage?
What would the product look like if we removed current constraints?
What would make users say "I didn't know I needed this"?

Narrow to user-specified domain if provided.

从以下角度进行分析。并非所有角度都适用于每个产品——使用相关的角度：

使用情况与行为 — 用户实际在做什么？

如果有分析工具可用，检查使用模式、转化漏斗、留存率和流失点
识别被高频使用的功能（加大投入）与未被使用的功能（裁剪或重新思考）

需求 — 用户在请求什么？

检查问题跟踪器、功能请求积压和支持渠道中的模式
寻找频繁被请求的功能或常见的投诉

痛点 — 哪些功能损坏或使用起来令人沮丧？

检查

docs/reference/pitfalls/

和

docs/reference/runbooks/

中反复出现的运维痛点

查看错误报告、事件历史和支持升级记录

战略方向 — 当前的发展方向是什么？

阅读
```
docs/roadmap/
```
中的现有计划及其状态
阅读
```
docs/reference/features/
```
中的差距、限制和自然的下一步计划
考虑用户传达的业务目标和优先级

市场环境 — 外部发生了什么？

如果相关，研究竞争对手、相邻工具和市场变化
识别其他参与者正在利用的机会

技术机遇 — 代码库揭示了什么？

扫描代码中的
```
TODO
```
,
```
FIXME
```
,
```
HACK
```
, 存根和死代码路径
识别正在积极拖慢开发速度的技术债务

愿景 — 哪些尚未存在的功能是可行的？

利用已构建的功能可以解决哪些相邻问题？
可以利用哪些新兴功能或趋势？
如果消除当前限制，产品会是什么样子？
什么功能会让用户说“我之前都不知道我需要这个”？

如果用户指定了领域，缩小到该领域的候选事项。

2. Rank candidates

2. 对候选事项排名

Rank by:

impact (user value, pain reduction)
readiness (how much groundwork already exists)
size (
```
small
```
,
```
medium
```
,
```
large
```
)

按以下维度排名：

影响（用户价值、痛点缓解）
就绪度（已完成的基础工作有多少）
规模（
```
small
```
（小）、
```
medium
```
（中）、
```
large
```
（大））

3. Propose shortlist

3. 提出候选短名单

Use this exact header:

| # | What | Why now | Size | Readiness | Exists | Missing |
|---|------|---------|------|-----------|--------|---------|

使用以下精确表头：

| 序号 | 内容 | 为什么现在做 | 规模 | 就绪度 | 现有基础 | 缺失部分 |
|------|------|--------------|------|--------|----------|----------|

4. Formalize the chosen item

4. 规范化选定的事项

Once the user picks an item (or accepts the recommendation):

Create a roadmap doc at

docs/roadmap/proposed/YYYY-MM-DD-slug.md

Required sections:
- Opening line (plain-language summary of the problem)
- Status (
```
Proposed
```
  )
- Why (problem statement, evidence, user impact)
- What (concrete scope, deliverables)
- How It Fits In (relation to existing systems, dependencies)
- Non-Goals (explicit scope boundaries)
- Open Questions (unresolved decisions)
Add cross-links from related reference docs if useful

一旦用户选定了某个事项（或接受推荐）：

在

docs/roadmap/proposed/YYYY-MM-DD-slug.md

路径下创建路线图文档

必须包含以下章节：
- 开头行（用通俗易懂的语言总结问题）
- 状态（
```
Proposed
```
  ）
- 原因（问题陈述、证据、用户影响）
- 内容（具体范围、交付成果）
- 适配性（与现有系统的关系、依赖项）
- 非目标（明确的范围边界）
- 待解决问题（未决定的事项）
如果有用，从相关参考文档添加交叉链接

Output Contract (required)

输出约定（强制要求）

When

/docs research

completes, return all of:

Shortlist table (3-5 rows)
Recommended item (
```
#<n>
```
+ one-sentence reason)
If formalized: roadmap doc path, open questions
Next command suggestion (
```
/docs work <path>
```
or another
```
/docs research
```
for a different domain)

当

/docs research

完成时，必须返回以下所有内容：

候选短名单表格（3-5行）
推荐事项（
```
#<n>
```
+ 一句话理由）
如果已规范化：路线图文档路径、待解决问题
下一步命令建议（
```
/docs work <path>
```
或针对其他领域的另一个
```
/docs research
```
）

work

Execute a roadmap item. Build it, then close the loop in docs.

执行路线图事项。构建完成后，完成文档闭环。

1. Understand task

1. 理解任务

If user gives a roadmap doc path, read it first
If user gives a description, find the related roadmap doc in
```
docs/roadmap/
```
If no roadmap doc exists, ask: should we create one first (
```
/docs research
```
) or proceed directly?
If ambiguous, clarify scope briefly
Move the roadmap doc to
```
in-progress/
```
if it's still in
```
proposed/
```

如果用户提供了路线图文档路径，先阅读该文档
如果用户提供了描述，在
```
docs/roadmap/
```
中找到相关的路线图文档
如果没有路线图文档，询问：是否需要先创建一个（
```
/docs research
```
）还是直接进行？
如果存在歧义，简要澄清范围
如果路线图文档仍在
```
proposed/
```
中，将其移至
```
in-progress/
```

2. Gather implementation context

2. 收集实现上下文

Read the roadmap doc and any related reference docs
Inspect existing code patterns in touched areas
Check project rules and conventions

阅读路线图文档和所有相关参考文档
检查受影响区域的现有代码模式
查看项目规则和约定

3. Build

3. 构建

Plan first if scope is large (using your environment's planning workflow)
Implement the change
Run verification commands

如果范围较大，先进行规划（使用你的环境中的规划工作流）
实现更改
运行验证命令

4. Close the loop

4. 完成闭环

After implementation is complete:

Update reference docs — create or update
```
docs/reference/
```
docs to reflect the new code (features, architecture, conventions, runbooks, pitfalls as appropriate)

Update roadmap doc — move to

completed/

and update

## Status

Completed (YYYY-MM-DD)

, or move to

completed/

with

Partially Completed (YYYY-MM-DD)

and notes on what remains

Log entry — append a summary to
```
docs/logs/YYYY-MM.md
```

实现完成后：

更新参考文档 — 创建或更新
```
docs/reference/
```
中的文档以反映新代码（根据情况放入features、architecture、conventions、runbooks、pitfalls）
更新路线图文档 — 移至
```
completed/
```
并将
```
## Status
```
更新为
```
Completed (YYYY-MM-DD)
```
，或者移至
```
completed/
```
并标记为
```
Partially Completed (YYYY-MM-DD)
```
，同时注明剩余工作
日志条目 — 将摘要追加到
```
docs/logs/YYYY-MM.md
```
中

Output Contract (required)

输出约定（强制要求）

When

/docs work

completes, return all of:

Scope delivered
Code files changed
Verification — commands + pass/fail
Docs updated — list reference/roadmap/log paths, or
```
none
```
Follow-ups — remaining work or
```
none
```

当

/docs work

完成时，必须返回以下所有内容：

交付的范围
更改的代码文件
验证结果 — 命令 + 通过/失败
更新的文档 — 列出参考/路线图/日志的路径，或
```
none
```
（无更改）
后续工作 — 剩余工作或
```
none
```
（无后续）