ogt-docs-define

📄 结构化概念定义与文档规范

来自 OpenClaw 的文档定义指南,通过标准化模板与生命周期管理,帮助团队建立概念共识与知识基础。

收藏
4.4k
安装
945
版本
v1.0.0
CLS 安全性认证2026-06-04
点击查看完整报告 >

使用说明

核心用法

ogt-docs-define 是一个系统化的文档定义指南,旨在帮助团队建立"事物本质"的共享理解。它通过规范化的方法论指导用户创建定义文档(Definition Documents),回答"这是什么、为什么存在、边界在哪里、与其他事物的关系"等核心问题。该 Skill 采用"文件夹即实体"(Folder-as-Entity)模式,将每个概念、实体或系统组织为独立文件夹,内部包含主定义文件、补充说明及信号文件(Signal Files),并通过草稿、审核、批准、弃用等生命周期状态管理文档演进。

显著优点

首先,该 Skill 提供了完整的分类体系,涵盖商业概念、产品功能、技术架构、营销定位、品牌标识及开发工具六大领域,确保不同类型的定义都有据可依。其次,其生命周期管理机制通过 .draft.ready_for_review.approved 等信号文件实现状态流转,强制引入审核流程,有效防止未经充分讨论的定义进入生产环境。第三,强调"边界定义"(What it is NOT),通过明确排除范围来预防概念蔓延。第四,内置关系映射表格,强制要求定义间关联,避免知识孤岛。最后,提供的模板与检查清单(Quality Checklist)大幅降低了文档编写的认知负担。

潜在缺点与局限性

该 Skill 的主要局限在于其较重的流程负担。信号文件系统虽然严谨,但增加了文件系统操作的复杂性,对于习惯简单 Markdown 文档的团队可能显得过度工程化。其次,严格的分类体系(business/features/technical 等)可能无法适配所有组织的独特知识结构,灵活性不足。此外,维护定义文档本身需要持续投入,在快速迭代的初创环境中,文档过时风险较高。最后,纯文本的定义方式缺乏交互性,对于复杂系统的可视化表达能力有限。

适合的目标群体

此 Skill 最适合中大型技术团队、采用文档优先(Docs-as-Code)文化的组织、以及需要维护复杂领域知识库(Domain Knowledge Base)的项目。特别适合那些面临"概念混淆、术语不统一、知识传承困难"问题的团队,或需要建立企业架构标准(Enterprise Architecture)的场景。对于个人开发者或小型短期项目,该规范可能过于繁重。

使用风险

作为纯文档型 Skill,其技术安全风险极低,无代码执行、网络通信或数据收集行为。主要风险集中在组织层面:流程采纳阻力(团队可能抵触严格的审核流程)、模板僵化风险(过度依赖模板可能抑制创新)、以及与现有 Wiki 或文档系统的整合成本。建议渐进式采用,先从关键核心概念开始试点。

安全解读

核心用法

ogt-docs-define 是 OGT(OpenClaw Guide Tree)文档系统中的基础定义指南 Skill,用于创建标准化的定义文档(definition documents),回答"某物是什么"的核心问题。其核心流程为:

1. 类型路由:根据定义类型自动路由至 6 个专业子 Skill(business/feature/code/marketing/branding/tools)
2. 信息收集:通过 9 个核心问题澄清概念边界、存在理由和关联关系

3. 文档生成:使用标准化模板输出包含 Overview、Core Concept、Boundaries、Relationships、Examples 的 Markdown 文件

4. 生命周期管理:通过 signal files(.draft/.ready_for_review/.approved/.deprecated)实现定义的版本控制和状态流转

5. 文件夹模式:每个定义以独立文件夹承载,内含主定义文件、扩展文件和状态信号文件

显著优点

  • 标准化程度高:强制包含边界定义(What it is NOT)和关系映射,避免概念漂移
  • 生命周期完整:从 draft → review → approved → deprecated 的完整状态机,支持版本追溯
  • 零执行风险:纯 Markdown 文档(T-MD 分类),无可执行代码、无网络调用、无依赖
  • 可扩展性强:6 个专业子 Skill 覆盖业务/产品/技术/营销/品牌/工具全领域
  • 质量内建:内置 8 项质量检查清单,强制要求具体示例和开放问题记录

潜在局限

  • 学习成本:signal files 机制和文件夹模式对新手有一定认知负担
  • 工具链依赖:需配合 Git 工作流和文件系统操作,纯 Web 环境使用受限
  • 子 Skill 耦合:核心功能依赖未展示的子 Skill 实现,完整能力需整套技能树
  • 审批瓶颈:手动 review/approval 流程在快速迭代场景可能成为阻滞点

适合人群

  • 技术写作者/文档工程师:需要建立可维护的术语体系和概念定义库
  • 系统架构师:需要为技术组件、数据模型、服务边界建立权威定义
  • 产品经理:需要为功能特性、用户类型、商业模式创建团队共识
  • 开源项目维护者:需要标准化的贡献者指南和术语规范

常规风险

  • 定义僵化风险:approved 状态定义被过度引用后难以演进,建议配合 .version 文件管理迭代
  • 子 Skill 失效风险:若 ogt-docs-define-* 子技能未安装,路由表中的跳转将失效
  • 权限管理缺失:signal files 无写权限控制,需依赖 Git 工作流保障状态变更合规性

ogt-docs-define 内容

手动下载zip · 4.3 kB
SKILL.mdtext/markdown
请选择文件