Project Documentation

核心用法

project-documentation 是一个工程文档元技能（Meta-Skill），采用"文档优先（Docs-First）"方法论，强制要求团队在编码前先定义问题、用户画像、功能需求和技术栈。核心交付物包括五类标准化文档：

• ADR（架构决策记录）：记录技术选型理由与权衡
• PRD（产品需求文档）：定义问题、用户、需求边界与成功指标
• Persona（用户画像）：描述目标用户的背景、痛点与使用旅程
• Runbook（运维手册）：可执行的操作步骤与故障排查指南
• Roadmap（路线图）：分离当前迭代与待办事项

目录结构规范

技能强制区分Current State（现状）与Future（规划）文档，避免用户混淆。architecture/、guides/、runbooks/ 面向真实系统状态，可公开；planning/ 存放未来规格，仅限内部。

质量门禁

提供7项发布前检查清单，核心红线包括：禁止混合未来计划与当前状态、禁止规划文档上站点、禁止文档一次性写完即弃。

显著优点

1. 方法论完整性：ADR+PRD+Persona 的组合覆盖架构、产品、用户三层视角，减少"先写代码后补文档"的债务
2. 模板标准化：提供可直接使用的 Markdown 模板，降低团队启动成本
3. 状态隔离设计：通过目录结构强制分离"是什么"与"将是什么"，避免文档站信息过时
4. 反模式警示：明确列出5类常见错误（如单文档适配所有读者），帮助团队规避典型陷阱

潜在局限

• 适用规模门槛：Docs-First 流程对小规模快速原型项目可能显得过重，存在流程摩擦
• 执行依赖纪律：模板和结构提供了"形式"，但内容质量仍依赖团队写入时的自律，系统无法强制内容深度
• 技术栈偏向：示例中的 npx clawhub 安装命令暗示特定工具链（OpenClaw/Moltbot），对非该生态用户存在迁移成本
• 动态更新挑战：虽强调"Living docs"，但未提供自动化检测代码-文档漂移的机制，维护仍需人工驱动

适合人群

• 技术负责人/架构师：需要建立团队级决策记录规范
• 产品经理与工程师协作场景：PRD与ADR的双轨并行适合产品驱动型工程团队
• 中大型项目维护者：已有代码库需要补全或重构文档结构
• 开源项目维护者：需要对外提供清晰的架构说明与贡献指南

常规风险

• 文档腐败风险：若团队未建立"代码变更同步更新文档"的纪律，Current State 文档将迅速失效
• 过度设计风险：小团队可能因遵循完整模板而产生冗余文档，反而降低效率
• 工具锁定风险：clawhub 生态的安装命令可能限制跨平台使用，建议确认模板内容的工具无关性

核心用法

Project Documentation 是一款面向软件工程团队的文档工作流 Meta-Skill，专注于解决项目启动和文档治理中的结构性问题。其核心用法围绕「文档先行」（Docs-First）理念展开：在项目写第一行代码之前，先完成问题定义、用户画像、功能规划和架构决策。Skill 内置了完整的文档类型模板库，包括架构决策记录（ADR）、产品需求文档（PRD）、用户画像（Personas）、运维手册（Runbooks）等，每个模板都提供了可直接复用的 Markdown 结构和填写指南。

用户通过命令行工具 npx clawhub@latest install 安装后，可获得预设的目录结构建议——将文档明确区分为「当前状态」（Current State）和「未来规划」（Planning）两大类，前者面向最终用户和运维人员，后者仅用于内部协作。这种分离机制是 Skill 最具实践价值的设计，有效避免了「规划文档被误当现状发布」的常见混乱。

显著优点

第一，方法论沉淀：Skill 不仅是模板集合，更传递了成熟的工程文档治理经验，如 ADR 的五种状态管理、Persona 的四阶段用户旅程分析框架、Runbook 的「前提条件-步骤-验证-排障」四段式结构。第二，开箱即用的目录架构：docs/ 目录的六文件夹划分（architecture/guides/runbooks/planning/decisions/product）经过实战验证，团队可零思考成本落地。第三，明确的质量门禁：Skill 提供了文档发布前的自检清单（Quality Gates），帮助团队建立可持续的文档维护文化。第四，纯文本友好：所有模板均为 Markdown，与 Git、静态站点生成器、代码仓库无缝集成。

潜在缺点与局限性

首先，认知门槛：Docs-First 理念对习惯「先写代码后补文档」的开发者是行为模式改变，需要团队管理层推动才能有效落地。其次，模板僵化风险：Skill 提供的模板偏重通用性，对于特定领域（如硬件嵌入式、合规金融系统）可能需要大量定制。第三，无自动化集成：Skill 本身不包含 CI/CD 钩子、文档站点自动生成、过期检测等工程化能力，需团队自行搭建配套工具链。第四，中文生态局限：当前版本模板以英文语境设计，中文团队的本地化适配工作需自行完成。

适合的目标群体

该 Skill 最适合以下场景：初创公司技术团队建立首个项目文档体系、中型团队重构混乱的历史文档、技术负责人推行研发规范化治理、以及开源项目维护者希望降低社区贡献门槛。对个人开发者而言，可作为个人项目的文档习惯养成工具。不适合已有成熟文档平台（如 Confluence + Archimate 深度集成）的大型企业，或完全无技术写作需求的纯设计类项目。

使用风险

作为纯文档模板 Skill，其技术风险极低：无代码执行、无网络请求、无依赖项。但需关注流程风险——若团队未严格执行「Current vs Future」分离原则，可能导致用户文档与内部规划混淆，引发沟通事故。此外，模板中的示例命令（如 npx clawhub@latest install）虽本身无害，但若团队成员误将 Skill 的安装指令复制到生产环境脚本中，可能造成非预期行为。建议在使用前由技术负责人审阅模板内容，根据组织标准进行裁剪，并建立文档评审流程避免模板误用。