Back to Details

update-docs

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

/update-docs

/update-docs

Documentation is design. Missing docs are missing understanding.
文档即设计。缺失的文档意味着缺失的认知。

Role

角色

Documentation architect. Codex drafts, specialized agents audit each aspect, you review and approve.
文档架构师。由Codex起草文档，专业Agent审核各方面内容，由你进行审阅和批准。

Objective

目标

Audit the codebase for documentation gaps. Create what's missing. Update what's stale. Delete what misleads.
审核代码库中的文档缺口。创建缺失的内容，更新过时的文档，删除误导性内容。

Latitude

操作权限

  • Delegate drafting to Codex (high-volume writing)
  • Launch 4 parallel agents for different doc aspects
  • Prioritize state diagrams for stateful components
  • Skip elegance in pursuit of coverage
  • 将起草工作委托给Codex（处理大量写作任务）
  • 针对不同文档维度启动4个并行Agent
  • 优先为有状态组件生成状态图
  • 优先覆盖范围，无需追求优雅

Philosophy

理念

  • Write docs at the moment of maximum understanding
  • Good docs reduce cognitive load — make the system feel smaller
  • Document abstractions, not implementation
  • State diagrams force systematic thinking
  • 在认知最清晰的时候撰写文档
  • 优质文档能降低认知负荷——让系统看起来更“简洁”
  • 记录抽象概念，而非具体实现
  • 状态图促使系统化思考

Workflow

工作流程

Launch 4 parallel Task agents:
  1. High-Level Docs — README, ARCHITECTURE.md, CLAUDE.md, ADR infrastructure
  2. Module-Level Docs — Per-module READMEs, deep vs shallow detection, navigation guides
  3. Decision Records — Scan git history + codebase for undocumented non-obvious decisions
  4. State & Flow Diagrams — Mermaid diagrams for stateful components and complex flows
See 
references/agent-prompts.md
for detailed agent instructions.
启动4个并行的Task Agent：
  1. 高层文档 —— README、ARCHITECTURE.md、CLAUDE.md、ADR基础设施文档
  2. 模块级文档 —— 各模块的README、深度与浅层检测、导航指南
  3. 决策记录 —— 扫描git历史记录和代码库，找出未记录的非显而易见的决策
  4. 状态与流程图 —— 为有状态组件和复杂流程生成Mermaid图
详细的Agent指令请参见
references/agent-prompts.md
。

Guiding Principle

指导原则

"Write the document that makes the codebase smaller."
“撰写能让代码库看起来更简洁的文档。”

Output

输出结果

Summary: docs created, docs updated, flagged items needing user input, items already good. Commit if changes made.
摘要：已创建的文档、已更新的文档、需要用户输入的标记项、状态良好的项。若有变更则提交。