docs

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

/docs — Project Documentation

/docs — 项目文档

You are managing an agent-first documentation architecture. Your goal is to keep project documentation accurate, useful, and minimal.

你正在管理一套以Agent为核心的文档架构。你的目标是保持项目文档准确、实用且简洁。

Determine mode

确定模式

If the user explicitly says "init" or "setup", use Init mode.
If the project is missing core doc files (no ROADMAP.md, no design-docs/), suggest Init mode.
Otherwise, use Update mode.

如果用户明确说"init"或"setup"，使用初始化模式。
如果项目缺少核心文档文件（无ROADMAP.md、无design-docs/目录），建议使用初始化模式。
其他情况则使用更新模式。

Init mode

初始化模式

Scaffold the documentation structure for this project. Work with the user to flesh out each file — don't just create empty templates.

为项目搭建文档结构。与用户协作完善每个文件——不要仅创建空模板。

Steps

步骤

Assess what exists. Check for existing README.md, CLAUDE.md, ARCHITECTURE.md, etc. Don't overwrite existing content — integrate with it using these rules:
- README.md: Preserve existing content. Reorganize into template sections if the structure is loose, but keep the substance.
- CLAUDE.md: Never modify existing instructions. If there's no existing documentation section, append one using the template. If there's already a documentation section (or similar conventions like "work log" or "commit" instructions), show the user both the existing rules and the template rules, and ask which to keep or how to merge them. Existing project conventions take precedence over template defaults.
- ARCHITECTURE.md: If one exists, adopt its structure and fill gaps from the template. If not, create from template.
- Other files (ROADMAP, IDEAS, MARKETING): Create fresh from templates — these are unlikely to exist already.
Discuss scope with the user. Not every project needs every file. At minimum, most projects benefit from:
- README.md (what is this project?)
- ROADMAP.md (what needs to happen?)
- CLAUDE.md additions (agent maintenance instructions)
Larger projects may also want:
- ARCHITECTURE.md (system design)
- IDEAS.md (brainstorming backlog)
- MARKETING.md (go-to-market notes)
- design-docs/ and logs/ directories
Create files using the templates in
```
references/
```
as starting points. Each template is a separate file:
- ```
references/roadmap.md
```
  — ROADMAP.md template
- ```
references/ideas.md
```
  — IDEAS.md template
- ```
references/architecture.md
```
  — ARCHITECTURE.md template
- ```
references/marketing.md
```
  — MARKETING.md template
- ```
references/design-doc.md
```
  — design doc template
- ```
references/log.md
```
  — daily log template
- ```
references/claude-md.md
```
  — CLAUDE.md documentation section
Read only the templates you need. Adapt them to the project — don't use verbatim. Work with the user to fill in real content rather than leaving placeholders.
Add maintenance instructions to CLAUDE.md. Create CLAUDE.md if it doesn't exist. Use
```
references/claude-md.md
```
as the base. Adapt to what files were actually created (e.g., omit the IDEAS.md instruction if that file wasn't created).
Create initial log entry in
```
logs/
```
for today, noting the documentation setup.

评估现有内容。检查是否存在README.md、CLAUDE.md、ARCHITECTURE.md等文件。不要覆盖现有内容——遵循以下规则进行整合：
- README.md：保留现有内容。如果结构松散，可重新组织为模板章节，但需保留核心内容。
- CLAUDE.md：绝不修改现有指令。如果没有现有文档章节，使用模板追加内容。如果已有文档章节（或类似约定，如“工作日志”或“提交”指令），向用户展示现有规则和模板规则，询问保留哪一个或如何合并。现有项目约定优先于模板默认规则。
- ARCHITECTURE.md：如果已存在，采用其结构并补充模板中的缺失内容。如果不存在，基于模板创建。
- 其他文件（ROADMAP、IDEAS、MARKETING）：基于模板全新创建——这些文件通常不会预先存在。
与用户讨论范围。并非每个项目都需要所有文件。大多数项目至少应包含：
- README.md（项目介绍）
- ROADMAP.md（待办事项规划）
- CLAUDE.md补充内容（Agent维护指令）
大型项目可能还需要：
- ARCHITECTURE.md（系统设计）
- IDEAS.md（创意储备）
- MARKETING.md（市场推广笔记）
- design-docs/和logs/目录
使用
references/
中的模板创建文件。每个模板对应独立文件：
- ```
references/roadmap.md
```
  — ROADMAP.md模板
- ```
references/ideas.md
```
  — IDEAS.md模板
- ```
references/architecture.md
```
  — ARCHITECTURE.md模板
- ```
references/marketing.md
```
  — MARKETING.md模板
- ```
references/design-doc.md
```
  — 设计文档模板
- ```
references/log.md
```
  — 每日日志模板
- ```
references/claude-md.md
```
  — CLAUDE.md文档章节模板
仅读取所需模板。根据项目调整内容——不要直接照搬。与用户协作填充真实内容，而非留空占位符。
在CLAUDE.md中添加维护指令。如果CLAUDE.md不存在则创建它。以
```
references/claude-md.md
```
为基础，根据实际创建的文件进行调整（例如，如果未创建IDEAS.md，则省略相关指令）。
在
logs/
中创建初始日志条目，记录当日的文档搭建情况。

Update mode

更新模式

Review recent work and bring documentation up to date.

回顾近期工作并更新文档至最新状态。

Steps

步骤

Scan recent activity. Check:
- ```
git log
```
  for recent commits since the last log entry. Find the newest file in
```
logs/
```
  to determine the cutoff date. If no prior log exists, scan the last ~20 commits for context.
- Current state of ROADMAP.md — are items stale? Anything done but not checked off?
- Existing design-docs — any need status updates?
- If
```
logs/
```
  doesn't exist yet, create it and start the first entry.
Update ROADMAP.md. Check off completed items with dates and commit hashes. Add any new work that's emerged. Move items between sections as needed.
Update or create today's log entry in
```
logs/
```
. Summarize what was done, link to relevant design-docs or commits. Focus on narrative — surprises, debugging insights, decisions made. Don't duplicate information that's already in design-docs.
Update design-docs if any active ones need status changes or new decisions recorded.
Surface gaps. Let the user know if you notice:
- Work that doesn't have a corresponding ROADMAP entry
- Decisions that aren't documented anywhere
- Stale items that might need to be moved to wontdo

Keep updates concise. The goal is accurate docs, not comprehensive prose.

扫描近期活动。检查：
- ```
git log
```
  中自上次日志条目以来的近期提交记录。找到
```
logs/
```
  中最新的文件以确定截止日期。如果之前无日志，扫描最近约20条提交记录获取上下文。
- ROADMAP.md的当前状态——是否有条目已过时？是否有已完成但未标记的内容？
- 现有设计文档——是否需要更新状态？
- 如果
```
logs/
```
  尚未存在，创建该目录并添加第一条日志。
更新ROADMAP.md。标记已完成的条目并添加日期和提交哈希值。添加新出现的工作内容。根据需要在章节间移动条目。
更新或创建当日的
logs/
日志条目。总结已完成的工作，链接至相关设计文档或提交记录。重点叙述过程——意外情况、调试心得、做出的决策。不要重复设计文档中已有的信息。
更新设计文档，如果有活跃的设计文档需要更新状态或记录新决策。
指出存在的缺口。如果发现以下情况，告知用户：
- 存在无对应ROADMAP条目的工作
- 决策未记录在任何文档中
- 过时条目可能需要移至wontdo章节

保持更新简洁。目标是确保文档准确，而非撰写详尽的长篇内容。

File reference

文件参考

When creating or updating these files, read the corresponding template from

references/

for the expected structure.

File	Template	Purpose	When to update
`README.md`	—	Project goal, what this is	When the project scope changes
`ARCHITECTURE.md`	`references/architecture.md`	System design, components	When architecture changes
`ROADMAP.md`	`references/roadmap.md`	Status, active work, done, wontdo	After completing or starting work
`IDEAS.md`	`references/ideas.md`	Brainstorming, not-yet-ready	When ideas come up
`MARKETING.md`	`references/marketing.md`	Positioning, distribution, content	When marketing strategy evolves
`design-docs/YYYY-MM-DD-*.md`	`references/design-doc.md`	Feature specs and plans	When planning or after key decisions
`logs/YYYY-MM-DD.md`	`references/log.md`	Daily narrative	After each work session
`CLAUDE.md` (docs section)	`references/claude-md.md`	Agent maintenance instructions	During init

创建或更新这些文件时，请读取

references/

中对应的模板以了解预期结构。

文件	模板	用途	更新时机
`README.md`	—	项目目标、项目介绍	项目范围变更时
`ARCHITECTURE.md`	`references/architecture.md`	系统设计、组件说明	架构变更时
`ROADMAP.md`	`references/roadmap.md`	状态跟踪、进行中工作、已完成、不会做	完成或启动工作后
`IDEAS.md`	`references/ideas.md`	创意头脑风暴、待完善内容	产生新想法时
`MARKETING.md`	`references/marketing.md`	定位、推广、内容规划	营销策略调整时
`design-docs/YYYY-MM-DD-*.md`	`references/design-doc.md`	功能规格与规划	规划功能或做出关键决策后
`logs/YYYY-MM-DD.md`	`references/log.md`	每日工作叙述	每次工作会话后
`CLAUDE.md` （文档章节）	`references/claude-md.md`	Agent维护指令	初始化期间