OGT 文档 —— 以文档为唯一真实来源

理念

文档是决策的数据库，代码仅是其具体实现。

┌─────────────────────────────────────────────────────────────────┐
│                    文档优先原则（DOC-FIRST PRINCIPLE）          │
├─────────────────────────────────────────────────────────────────┤
│  1. 文档定义某事物“是什么”（WHAT it IS）                        │
│  2. 代码实现文档所规定的内容                                    │
│  3. 文档与代码冲突时，以文档为准                                │
│                                                                 │
│  若文档写明为 X，而代码实现为 Y → 代码错误                      │
└─────────────────────────────────────────────────────────────────┘

何时使用本技能

当您需要以下操作时，请使用 ogt-docs：

• 理解 docs/ 目录结构
• 为特定任务选取合适的子技能
• 初始化一个“文档优先”的新项目
• 在不同类型的定义之间导航

针对具体任务，请使用下方列出的专业化子技能。

文档结构概览

docs/
├── definitions/              # “是什么”（WHAT things ARE）
│   ├── business/             # 商业模式、定价、用户
│   ├── features/             # 产品功能与规格
│   ├── technical/            # 架构、服务、数据
│   └── domain/               # 领域专属概念
│
├── rules/                    # “如何实现”（HOW to IMPLEMENT）
│   ├── code/                 # 编码规范
│   │   ├── frontend/
│   │   ├── backend/
│   │   └── infra/
│   ├── git/                  # 版本控制规则
│   └── domain/               # 领域专属规则
│
├── todo/                     # 任务管理（TASK management）
│   ├── pending/              # 尚未开始
│   ├── in_progress/          # 正在进行中
│   ├── review/               # 等待审核
│   ├── blocked/              # 阻塞中（无法推进）
│   ├── done/                 # 已完成且已验证
│   └── rejected/             # 已拒绝的任务
│
├── guides/                   # 操作指南类文档（HOW-TO documents）
│   └── {topic}/
│
└── social/                   # 市场营销与传播内容
    ├── campaigns/
    ├── content/
    └── branding/

“文件夹即实体”模式（Folder-as-Entity Pattern）

每个可文档化的条目均表示为一个文件夹，内含：

{item_slug}/
├── {type}.md                 # 主文档（如 task.md、feature.md 等）
├── {supporting_files}.md     # 补充性文档
└── .{signal_files}           # 状态标记与元数据

优势：

• 可将整个文件夹整体迁移至工作流的不同阶段
• 可附加任意数量的补充文档
• 通过点文件（dot-files）直观表达状态
• 支持原子级版本控制与变更追踪

子技能参考

定义类（WHAT things ARE）

规则类（HOW to IMPLEMENT）

任务类（WHAT to DO）

其他

工作流概览

flowchart TB
    subgraph define ["1. 定义（DEFINE）"]
        D1[创建定义]
        D2[获取审批]
    end

    subgraph regulate ["2. 规范（REGULATE）"]
        R1[创建规则]
        R2[添加示例]
    end

    subgraph implement ["3. 实现（IMPLEMENT）"]
        I1[创建任务]
        I2[编写代码]
        I3[审核]
    end

    subgraph verify ["4. 验证（VERIFY）"]
        V1[运行检查]
        V2[确认一致性]
    end

    define --> regulate --> implement --> verify
    verify -->|不一致| implement
    verify -->|文档有误| define

快速入门

“我需要定义一个新事物”

→ 使用 ogt-docs-define 了解定义类型，再选用对应的具体子技能

“我需要创建一个任务”

→ 使用 ogt-docs-create-task

“我需要确认某项任务是否真正完成”

→ 使用 ogt-docs-audit-task

“我需要添加编码规范”

→ 使用 ogt-docs-rules-code，或根据需要选用前端/后端/基础设施专用变体

“我需要为新项目初始化文档体系”

→ 使用 ogt-docs-init

命名规范

信号文件参考

信号文件是用于指示状态或元数据的点文件（dot-files）。

黄金准则

1. 未被文档记录的事物，即视为不存在
2. 若代码与文档矛盾，则代码错误
3. 未经验证，切勿轻信“已完成”状态
4. 移动文件夹，而非复制文件
5. 使用点文件（dot-files）标注状态，而非修改状态字段