docfront

编写文档

项目的所有文档都存放在 docs/ 目录中。docfront CLI 让人类和 AI Agent 无需离开终端即可查找和阅读文档。

使用 CLI 浏览

通过项目的包管理器运行命令（例如 npm run docfront --、pnpm docfront）。

docfront                                          # list root docs
docfront --dir topic-a --dir topic-b/sub-topic-c  # list subdirectories
docfront --recursive                              # list everything
docfront --read doc-1.md topic-a/doc-2.md         # read documents (frontmatter stripped)
docfront --check                                  # validate all files

工作流

1. 了解主题 — 明确需要记录什么。如有不清楚之处，请询问用户。
2. 确定存放位置 — 扫描现有文档（docfront --recursive）。决定是新建文件还是使用现有文件，以及应放在哪个子目录。如有不清楚之处，请与用户讨论。
3. 编写 — 遵循以下约定。

编写指南

• 目标读者： 有经验的新手——具备技术能力，但不熟悉这个特定项目的人。
• 简洁具体——不写显而易见的信息，也不写泛泛的最佳实践。
• 文档通常为 40–80 行。
• 优先引用源文件，而不是使用大型代码块。
• 如果标题已清楚说明用途，则省略 summary。

文件和目录命名

• 新建文件和目录使用全小写连字符（kebab-case）。
• CLI 允许使用大写字母（例如 RELEASING.md）。
• 名称必须兼容 shell：不能包含空格、引号或特殊字符。CLI 会验证文件和目录名称。使用 docfront --check 进行检查。
• 所有文档均使用 .md（Markdown）格式。
• 使用简短且能说明内容的名称。
• 将相关文档归入子目录。子目录可以嵌套。

YAML Frontmatter

.md 文件可以以 YAML frontmatter 块开头。在有助于读者理解时添加，尤其是在文件名或标题本身不够明确时。它不是必需的；如果没有 frontmatter，CLI 会使用文档正文中的第一个 # heading 作为标题。字段如下：

字段	必需	说明
title	否	在列表中显示的易读名称。若缺失，则使用第一个 # heading。
summary	否	一句简洁的描述。如果标题已清楚说明用途，则省略此字段，避免重复。
read_when	否	由简短、以行动为导向的提示组成的 YAML 列表。每条提示都应补全这句话：“在你……时阅读本文档。”

文档正文

在 frontmatter 结束标记 --- 之后，编写标准 Markdown。正文格式不受限制，可按需使用标题、代码块、表格和列表。

---
title: Your Title Here
summary: A one-sentence description of what this document covers.
read_when:
  - first situation when this document is useful
  - second situation
---

# Your Title Here

Start your content here…

参考资料

• 安装 Docfront CLI — 如何将 docfront CLI 添加到项目中。
• 引导创建文档 — 通过探索代码库来创建或扩展项目文档的说明。
• 迁移现有文档 — 将现有 Markdown 文档目录转换为符合 docfront 约定（命名、frontmatter）的指南。
• 将 Skills 迁移到 Docfront 文档 — 将项目内部文档从 Agent 技能迁移到 docs/ 的指南。