fstack-document

/fstack-document

将当前项目的文档写入 .md 文件，分为三层：通俗易懂的概览、工作原理说明，以及更深入的参考。运行一次即可创建文档。再次运行，它会更新文档以匹配当前的代码。

何时使用

• 项目几乎没有或完全没有文档。
• 文档存在，但已与代码脱节。
• 用户调用 /fstack-document。

步骤

1. 通读项目：结构、入口点、主要模块、数据模型、配置，以及如何运行和测试它。
2. 检查 docs/ 是否已有 fstack 文档集（即下面三个文件）。
   • 如果没有 —— 创建模式。
   • 如果有 —— 更新模式。重新通读项目，与现有文档进行对比，只修改代码发生变化的部分。在人工编辑仍然成立的地方予以保留。不要从头重写。
3. 编写或更新以下三个文件，从通俗到深入：
   • docs/overview.md —— ELI5。 这个项目是什么、它做什么、面向谁，用非专家也能理解的语言。不要用术语。
   • docs/architecture.md —— 工作原理。 主要组成部分、它们如何组合、数据如何流动，以及塑造它的各项决策。
   • docs/reference.md —— 细节。 目录和关键文件、配置和环境、如何运行、测试和构建。
4. 展示一份你所编写或修改内容的简短摘要。在更新模式下，说明添加了什么、修订了什么，以及任何看起来已从代码中移除的内容。

保持同步

• 让文档匹配当前的代码 —— 不是 git 历史，也不是变更日志。
• 如果文档提到的某个文件、模块或功能已不存在，标记它并移除该部分。
• 如果存在文档遗漏的新内容，将其添加到正确的层级。

禁止事项

• 蔓延成许多文件。三个层级，三个文件。如果某个部分变得过于庞大，这是项目本身可能过于复杂的信号。
• 凭空编造行为。记录代码做了什么，而不是它应该做什么。如果有不清楚的地方，如实说明，而不是猜测。
• 重写代码未发生变化的文档。更新模式只触碰有变动的部分。
• 包含机密 —— 密钥、令牌或 .env 值。

示例

用户：/fstack-document

Agent：“还没有 docs/，所以正在创建这套文档。写了三个文件：

• docs/overview.md —— 用通俗的话说明这个应用是什么。
• docs/architecture.md —— Astro 页面、Convex 后端、认证流程。
• docs/reference.md —— 目录结构图、环境变量，以及运行/测试/构建命令。 要浏览一下吗？”

用户：/fstack-document （一周后）

Agent：“文档已存在 —— 更新模式。变更：在 architecture 和 reference 中添加了新的 /api/export 路由。修订了认证部分 —— 它从 sessions 改为 magic links。文档提到的 themes 模块已从代码中消失；我移除了那段。”