ogt-docs

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

OGT Docs - Documentation as Source of Truth

OGT Docs - 以文档为唯一可信源

Philosophy

核心理念

Documentation is the database of decisions. Code is merely its implementation.

┌─────────────────────────────────────────────────────────────────┐
│                    THE DOC-FIRST PRINCIPLE                      │
├─────────────────────────────────────────────────────────────────┤
│  1. Documentation DEFINES what something IS                     │
│  2. Code IMPLEMENTS what documentation specifies                │
│  3. Conflicts RESOLVE in favor of documentation                 │
│                                                                 │
│  If docs say X and code does Y → CODE IS WRONG                  │
└─────────────────────────────────────────────────────────────────┘

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

┌─────────────────────────────────────────────────────────────────┐
│                    文档优先原则                                  │
├─────────────────────────────────────────────────────────────────┤
│  1. 文档定义事物的本质                                           │
│  2. 代码实现文档所规定的内容                                     │
│  3. 出现冲突时以文档为准                                         │
│                                                                 │
│  如果文档规定是X而代码实现是Y → 代码存在错误                      │
└─────────────────────────────────────────────────────────────────┘

When to Use This Skill

何时使用该技能

Use

ogt-docs

when you need to:

Understand the docs/ folder structure
Find the right sub-skill for a specific task
Initialize a new docs-first project
Navigate between definition types

For specific tasks, use the specialized sub-skills listed below.

当你需要以下操作时，使用

ogt-docs

：

了解docs/目录结构
为特定任务找到合适的子技能
初始化一个新的文档优先项目
在不同定义类型间切换导航

针对特定任务，请使用以下列出的专用子技能。

Documentation Structure Overview

文档结构概览

docs/
├── definitions/              # WHAT things ARE
│   ├── business/             # Business model, pricing, users
│   ├── features/             # Product features and specs
│   ├── technical/            # Architecture, services, data
│   └── domain/               # Domain-specific concepts
│
├── rules/                    # HOW to IMPLEMENT
│   ├── code/                 # Coding standards
│   │   ├── frontend/
│   │   ├── backend/
│   │   └── infra/
│   ├── git/                  # Version control rules
│   └── domain/               # Domain-specific rules
│
├── todo/                     # TASK management
│   ├── pending/              # Not started
│   ├── in_progress/          # Being worked on
│   ├── review/               # Awaiting review
│   ├── blocked/              # Cannot proceed
│   ├── done/                 # Completed & verified
│   └── rejected/             # Declined tasks
│
├── guides/                   # HOW-TO documents
│   └── {topic}/
│
└── social/                   # Marketing & communications
    ├── campaigns/
    ├── content/
    └── branding/

docs/
├── definitions/              # 事物的本质
│   ├── business/             # 业务模型、定价、用户
│   ├── features/             # 产品功能与规格
│   ├── technical/            # 架构、服务、数据
│   └── domain/               # 领域专属概念
│
├── rules/                    # 实现规范
│   ├── code/                 # 编码标准
│   │   ├── frontend/
│   │   ├── backend/
│   │   └── infra/
│   ├── git/                  # 版本控制规则
│   └── domain/               # 领域专属规则
│
├── todo/                     # 任务管理
│   ├── pending/              # 未开始
│   ├── in_progress/          # 进行中
│   ├── review/               # 待审核
│   ├── blocked/              # 已阻塞
│   ├── done/                 # 已完成并验证
│   └── rejected/             # 已驳回
│
├── guides/                   # 操作指南文档
│   └── {topic}/
│
└── social/                   # 营销与传播
    ├── campaigns/
    ├── content/
    └── branding/

The Folder-as-Entity Pattern

文件夹即实体模式

Every documentable item is a folder containing:

{item_slug}/
├── {type}.md                 # Primary document (task.md, feature.md, etc.)
├── {supporting_files}.md     # Additional documentation
└── .{signal_files}           # Status markers and metadata

Benefits:

Move entire folder between workflow stages
Attach unlimited supporting files
Signal status via dot-files
Version and track changes atomically

每个可文档化的项都是一个文件夹，包含以下内容：

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

优势：

可将整个文件夹在工作流阶段间移动
可附加无限多的辅助文件
通过点文件标记状态
原子化地版本控制和跟踪变更

Sub-Skills Reference

子技能参考

Definitions (WHAT things ARE)

定义类（事物的本质）

Sub-Skill	Purpose	Use When
`ogt-docs-define`	General definition guidance	Need overview of definition types
`ogt-docs-define-business`	Business model, pricing, users	Defining business concepts
`ogt-docs-define-feature`	Product features and specs	Specifying a new feature
`ogt-docs-define-code`	Technical architecture	Defining services, data models
`ogt-docs-define-marketing`	Brand, messaging, audience	Marketing definitions
`ogt-docs-define-branding`	Visual identity, tone	Brand guidelines
`ogt-docs-define-tools`	Tooling and CLI specs	Defining developer tools

子技能	用途	适用场景
`ogt-docs-define`	通用定义指导	需要了解定义类型的概览时
`ogt-docs-define-business`	业务模型、定价、用户	定义业务概念时
`ogt-docs-define-feature`	产品功能与规格	定义新功能时
`ogt-docs-define-code`	技术架构	定义服务、数据模型时
`ogt-docs-define-marketing`	品牌、信息传递、受众	定义营销相关内容时
`ogt-docs-define-branding`	视觉标识、语气风格	定义品牌指南时
`ogt-docs-define-tools`	工具与CLI规格	定义开发者工具时

Rules (HOW to IMPLEMENT)

规则类（实现规范）

Sub-Skill	Purpose	Use When
`ogt-docs-rules`	General rules guidance	Need overview of rule types
`ogt-docs-rules-code`	Coding standards overview	General code rules
`ogt-docs-rules-code-front`	Frontend-specific rules	React, CSS, components
`ogt-docs-rules-code-back`	Backend-specific rules	API, database, services
`ogt-docs-rules-code-infra`	Infrastructure rules	Docker, CI/CD, deployment
`ogt-docs-rules-git`	Version control rules	Commits, branches, PRs

子技能	用途	适用场景
`ogt-docs-rules`	通用规则指导	需要了解规则类型概览时
`ogt-docs-rules-code`	编码标准概览	处理通用编码规则时
`ogt-docs-rules-code-front`	前端专属规则	处理React、CSS、组件相关内容时
`ogt-docs-rules-code-back`	后端专属规则	处理API、数据库、服务相关内容时
`ogt-docs-rules-code-infra`	基础设施规则	处理Docker、CI/CD、部署相关内容时
`ogt-docs-rules-git`	版本控制规则	处理提交、分支、PR相关内容时

Tasks (WHAT to DO)

任务类（待办事项）

Sub-Skill	Purpose	Use When
`ogt-docs-create-task`	Create and manage tasks	Need to create/update a task
`ogt-docs-audit-task`	Verify task completion	Checking if task is truly done

子技能	用途	适用场景
`ogt-docs-create-task`	创建与管理任务	需要创建或更新任务时
`ogt-docs-audit-task`	验证任务完成情况	检查任务是否真的完成时

Other

其他类

Sub-Skill	Purpose	Use When
`ogt-docs-create`	General creation guidance	Need to create any doc type
`ogt-docs-create-social`	Marketing content	Creating social/marketing content
`ogt-docs-audit`	General audit guidance	Auditing documentation
`ogt-docs-init`	Initialize docs structure	Setting up new project
`ogt-docs-config`	Configuration options	Customizing docs workflow

子技能	用途	适用场景
`ogt-docs-create`	通用创建指导	需要创建任意类型文档时
`ogt-docs-create-social`	营销内容创建	创建社交/营销类内容时
`ogt-docs-audit`	通用审核指导	审核文档内容时
`ogt-docs-init`	初始化文档结构	搭建新项目的文档体系时
`ogt-docs-config`	配置选项说明	自定义文档工作流时

Workflow Overview

工作流概览

mermaid

flowchart TB
    subgraph define ["1. DEFINE"]
        D1[Create Definition]
        D2[Get Approval]
    end

    subgraph regulate ["2. REGULATE"]
        R1[Create Rules]
        R2[Add Examples]
    end

    subgraph implement ["3. IMPLEMENT"]
        I1[Create Task]
        I2[Write Code]
        I3[Review]
    end

    subgraph verify ["4. VERIFY"]
        V1[Run Checks]
        V2[Confirm Match]
    end

    define --> regulate --> implement --> verify
    verify -->|Mismatch| implement
    verify -->|Docs Wrong| define

mermaid

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

    subgraph regulate ["2. 制定规则"]
        R1[创建规则文档]
        R2[添加示例]
    end

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

    subgraph verify ["4. 验证"]
        V1[运行检查]
        V2[确认匹配]
    end

    define --> regulate --> implement --> verify
    verify -->|不匹配| implement
    verify -->|文档错误| define

Quick Start

快速开始

"I need to define something new"

"我需要定义新内容"

→ Use

ogt-docs-define

to understand types, then the specific sub-skill

→ 使用

ogt-docs-define

了解定义类型，再使用对应的专用子技能

"I need to create a task"

"我需要创建一个任务"

→ Use

ogt-docs-create-task

→ 使用

ogt-docs-create-task

"I need to check if a task is really done"

"我需要检查任务是否真的完成"

→ Use

ogt-docs-audit-task

→ 使用

ogt-docs-audit-task

"I need to add coding rules"

"我需要添加编码规则"

→ Use

ogt-docs-rules-code

or the specific frontend/backend/infra variant

→ 使用

ogt-docs-rules-code

或对应的前端/后端/基础设施子技能

"I need to set up docs for a new project"

"我需要为新项目搭建文档体系"

→ Use

ogt-docs-init

→ 使用

ogt-docs-init

Naming Conventions

命名规范

Element	Format	Example
Folder slugs	snake_case	`global_search` , `user_auth`
Primary files	lowercase type	`task.md` , `feature.md` , `rule.md`
Supporting files	lowercase descriptive	`phase_0.md` , `notes.md` , `progress.md`
Signal files	dot + snake_case	`.blocked_reason` , `.approved_by_human`

元素	格式	示例
文件夹别名	蛇形命名法（snake_case）	`global_search` 、 `user_auth`
主文件	小写类型名	`task.md` 、 `feature.md` 、 `rule.md`
辅助文件	小写描述性名称	`phase_0.md` 、 `notes.md` 、 `progress.md`
标识文件	点+蛇形命名法	`.blocked_reason` 、 `.approved_by_human`

Signal Files Reference

标识文件参考

Signal files are dot-files that indicate status or metadata.

Signal	Type	Meaning
`.version`	Content	Schema/doc version (JSON)
`.blocked`	Empty	Item is blocked
`.blocked_reason`	Content	Why it's blocked
`.approved`	Empty	Approved for implementation
`.approved_by_{name}`	Empty	Who approved
`.rejected`	Empty	Rejected
`.rejected_reason`	Content	Why rejected
`.verified`	Empty	Implementation verified
`.completed_at`	Content	Completion timestamp
`.assigned_to_{agent}`	Empty	Who's working on it
`.pr_link`	Content	Associated PR URL
`.depends_on`	Content	Dependencies list

标识文件是用于指示状态或元数据的点文件。

标识文件	类型	含义
`.version`	含内容文件	架构/文档版本（JSON格式）
`.blocked`	空文件	该项已被阻塞
`.blocked_reason`	含内容文件	阻塞原因
`.approved`	空文件	已获批可执行
`.approved_by_{name}`	空文件	审批人
`.rejected`	空文件	已驳回
`.rejected_reason`	含内容文件	驳回原因
`.verified`	空文件	实现已验证
`.completed_at`	含内容文件	完成时间戳
`.assigned_to_{agent}`	空文件	处理人
`.pr_link`	含内容文件	关联的PR URL
`.depends_on`	含内容文件	依赖项列表

The Golden Rules

黄金准则

If it's not documented, it doesn't exist
If code contradicts docs, code is wrong
Never trust "done" status without verification
Move folders, don't copy files
Signal with dot-files, don't edit status fields

未记录的内容，视为不存在
若代码与文档冲突，代码存在错误
未经验证，切勿相信“已完成”状态
移动文件夹，而非复制文件
使用点文件标记状态，而非编辑状态字段