ogt-docs

ogt-docs 是一个基于"文档即真理源"（Documentation-as-Source-of-Truth）理念的技能，旨在通过规范化的 docs/ 目录结构，将文档作为项目决策的唯一权威来源。该技能采用"文档定义、代码实现、冲突以文档为准"的核心原则，为技术团队提供了一套完整的文档驱动开发工作流框架。

核心用法围绕 Folder-as-Entity 模式展开，将每个可文档化项表示为包含主文档、支持文件和状态标记（dot-files）的文件夹。通过 definitions/（定义事物本质）、rules/（实现规则）、todo/（任务管理）、guides/（操作指南）和 social/（营销传播）五大目录，配合 20 余个专业化子技能（如 ogt-docs-define-feature、ogt-docs-rules-code 等），实现从业务定义到代码规范再到任务执行的全链路文档化管理。用户可通过路由式交互，根据具体需求调用相应子技能完成文档创建、审计和状态流转。

显著优点在于其强制性的文档优先约束，确保"未文档化即不存在"，从根本上解决代码与文档脱节的技术债问题。状态信号文件（如 .blocked、.approved、.verified）机制提供了轻量级的工作流管理，无需复杂工具即可实现任务状态追踪。此外，Mermaid 流程图和 ASCII 架构图的结合，使文档本身具备可视化表达能力，降低团队沟通成本。

潜在缺点包括较高的采用门槛：团队需要完全接受"代码服从文档"的逆向思维，这对传统开发习惯是重大转变。T3 级别的个人开发者来源（eduardou24）意味着缺乏组织级背书，企业用户需自行验证方法论的有效性。此外，该技能仅提供指导性规范，不具备自动化执行能力，实际落地需配合其他工具或子技能，可能增加工具链复杂度。

适合的目标群体主要是技术团队负责人、文档工程师、开源项目维护者以及追求工程规范化的中小团队。特别适合需要严格合规审计的金融、医疗等行业，以及分布式协作的远程团队。对于已有成熟文档体系的大型企业，可作为补充规范参考。

使用风险方面，作为纯文档型技能，本身无代码执行风险，但存在指导与实践脱节的可能。若团队成员未能严格遵循 Folder-as-Entity 规范，可能导致文档结构混乱。此外，引用的子技能（如 ogt-docs-init、ogt-docs-audit-task 等）安全性需单独评估，建议在使用前审查各子技能的权限申请和代码实现。性能风险较低，但需注意文档膨胀可能导致的信息检索效率下降。

核心用法

ogt-docs 是一套文档优先的项目管理方法论，核心主张「文档即真相，代码仅实现」。它将 docs/ 目录作为项目的权威数据源，涵盖定义（definitions）、规则（rules）、任务（todo）、指南（guides）和社交内容（social）五大板块。

典型使用场景：

• 初始化新项目时，使用 ogt-docs-init 建立标准文档结构
• 定义新功能时，先用 ogt-docs-define-feature 编写规格，再派生开发任务
• 编码阶段通过 ogt-docs-rules-code-* 系列子技能获取具体规范
• 任务流转采用「文件夹即实体」模式，通过移动文件夹和点文件（如 .blocked、.approved）管理状态

工作流四阶段： DEFINE（定义）→ REGULATE（制定规则）→ IMPLEMENT（实现）→ VERIFY（验证），形成闭环。

显著优点

1. 单向权威源：明确「文档定义本质，代码实现表象，冲突以文档为准」，解决长期存在的文档与代码脱节问题
2. 原子化版本管理：文件夹级组织支持 Git 原子提交，点文件机制提供轻量级状态追踪
3. 高度可扩展：子技能路由设计清晰，从业务定义到基础设施规则均有专用入口
4. 生产就绪安全：纯 Markdown 结构，无可执行代码，天然免疫代码注入和供应链攻击

局限性与风险

• 执行依赖人工：无自动化 enforcement 机制，规则遵守全靠开发者自觉
• 认知迁移成本：需要团队接受「先写文档后写代码」的思维转变，传统开发团队适应期较长
• 规模边界：未明确说明超大型项目（数千文档）的性能与导航策略
• 工具链缺失：当前无配套 CLI 或 IDE 插件，状态流转需手动操作文件系统

适合人群

• 追求极致文档规范的中小型技术团队
• 开源项目维护者，需向贡献者明确传达设计意图
• 高度监管行业（金融、医疗）的合规敏感型项目
• 远程协作团队，依赖异步文档沟通替代实时会议

常规风险

该 Skill 本身无技术风险，但实施层面的「文档腐化」风险需警惕：文档若不能及时更新，将成为阻碍而非助力。建议配套定期审计流程（ogt-docs-audit 子技能）。