Back to Details

cmd-idiot-proof-docs

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Simple Docs for Humans and Agents

面向人类与Agent的简洁文档

Use this command to write or rewrite documentation so it is simple, fast to scan, and easy to execute.
使用该命令编写或重写文档，使其简洁、扫读速度快、易于执行。

Primary Goal

核心目标

  • Bias toward simple docs.
  • Start with the shortest successful path.
  • Preserve original meaning and factual content while reordering for clarity.
  • 倾向于编写简洁文档。
  • 以最短的可行路径开篇。
  • 保留原文含义与事实内容，同时重新排版以提升清晰度。

Required Output Order

输出顺序要求

  1. Quickstart (always first)
  2. Main workflow
  3. Configuration/reference tables (when relevant)
  4. Alternative paths (only when they are true user/code path alternatives)
  5. Extra details at the end inside 
    <details><summary>...</summary>...</details>
  1. 快速上手（始终放在首位）
  2. 核心工作流
  3. 配置/参考表格（适用于相关场景）
  4. 替代路径（仅当确实是用户/代码层面的替代路径时添加）
  5. 额外细节放在末尾的
    <details><summary>...</summary>...</details>
    标签内

Approval Gate (Required)

审批门槛（必填）

  • Before editing any file, show a change preview for approval.
  • Use this exact preview structure for each file:
    • Additions
    • Removals
    • Changes
  • Show the concrete text to be added, removed, or changed.
  • Wait for explicit user approval before applying edits.
  • Apply only the approved edits.
  • If approval is not granted, do not modify files.
  • 编辑任何文件前，先展示变更预览以供审批。
  • 每个文件的预览都严格遵循以下结构：
    • 新增内容
    • 移除内容
    • 变更内容
  • 展示将被新增、移除或变更的具体文本。
  • 应用编辑前需等待用户明确批准。
  • 仅应用已获批的编辑内容。
  • 若未获得批准，不得修改文件。

Core Rules

核心规则

  • Optimize for both human readers and agent readers.
  • Maximize copy-paste command snippets.
  • Prefer short sections and concise language.
  • Use Markdown tables when information is structured.
  • Use Mermaid diagrams when they improve understanding of flow or architecture.
  • Avoid unnecessary sections.
  • Avoid "Optional" sections unless they represent an actual alternate path.
  • Put superfluous/background material at the end.
  • Add "Code Structure" only when repository layout helps task completion.
  • 同时优化面向人类读者与Agent读者的阅读体验。
  • 尽量提供可直接复制粘贴的命令片段。
  • 优先使用短段落与简洁表述。
  • 信息结构化时使用Markdown表格。
  • 当Mermaid图能提升流程或架构的理解度时使用。
  • 避免不必要的章节。
  • 避免“可选”章节，除非它们确实对应替代路径。
  • 将多余/背景材料放在文档末尾。
  • 仅当仓库布局有助于完成任务时添加“代码结构”章节。

Command Block Rules (Strict)

代码块规则（严格执行）

  • Do not place comments inside bash code blocks.
  • Put labels outside code blocks.
Correct pattern:
Start the server:
bash
make start_server
Run a command:
bash
make run_command
Incorrect pattern (separate steps combined in one unlabeled block):
bash
make start_server
make run_command
  • 不要在bash代码块内添加注释。
  • 将说明标签放在代码块外部。
正确示例：
启动服务器：
bash
make start_server
运行命令：
bash
make run_command
错误示例（不同步骤合并在一个无标签代码块中）：
bash
make start_server
make run_command

Section Defaults

默认章节

Use only sections that add value for the specific document. Default section set:
  • Quickstart
  • Main Workflow
  • Configuration
  • Code Structure (only if useful)
  • Troubleshooting (only for real recurring issues)
仅使用对特定文档有价值的章节。默认章节集合：
  • 快速上手
  • 核心工作流
  • 配置
  • 代码结构（仅当有用时添加）
  • 故障排查（仅针对实际高频出现的问题添加）

Configuration Table Format

配置表格格式

If environment variables or configuration values are required, use this format:
NamePurposeDefault
APP_ENV
Runtime environment
development
API_URL
Base URL for API calls
http://localhost:8000
如果需要填写环境变量或配置值，使用以下格式：
名称用途默认值
APP_ENV
运行时环境
development
API_URL
API调用的基础URL
http://localhost:8000

Details Block Rule

详情块规则

Move long explanations, implementation notes, and low-priority reference material into details blocks:
markdown
<details>
<summary>Deep dive: request lifecycle</summary>

Detailed explanation here.

</details>
将长篇说明、实现注释和低优先级参考材料放入详情块：
markdown
<details>
<summary>深度解析：请求生命周期</summary>

此处填写详细说明。

</details>

Deliverable

交付物

  • Return the final output as Markdown (
    .md
    ).
  • Keep all important content, but simplify, reorder, and prioritize for quick execution.
  • 以Markdown（
    .md
    ）格式返回最终输出。
  • 保留所有重要内容，但需进行简化、重排与优先级调整，以便快速执行。