OGT Docs - 创建

用于创建新文档实体的根技能。

概述

该技能根据您正在创建的文档类型，路由至对应的专用创建工作流。每个实体均以一个文件夹形式存在，并包含适当的文件与信号（signal）。

flowchart TB
    CREATE["ogt-docs-create"] --> TASK["ogt-docs-create-task"]
    CREATE --> DEF["ogt-docs-define"]
    CREATE --> RULE["ogt-docs-rules"]
    CREATE --> SOCIAL["ogt-docs-create-social"]
    CREATE --> CHANGE["ogt-docs-changelog"]

    TASK --> |folder| PENDING["docs/todo/pending/"]
    DEF --> |folder| DEFINE["docs/define/"]
    RULE --> |folder| RULES["docs/rules/"]
    SOCIAL --> |folder| CONTENT["docs/content/"]
    CHANGE --> |file| CHANGELOG["CHANGELOG.md"]

适用场景

• 创建新任务
• 添加定义（功能、代码、业务等）
• 建立新规则
• 创建社交/营销内容
• 更新变更日志（changelog）

快速参考

创建工作流

所有创建操作均遵循相同模式：

flowchart LR
    A[识别类型] --> B[创建文件夹]
    B --> C[复制模板]
    C --> D[填充内容]
    D --> E[添加信号]
    E --> F[验证结构]

步骤 1：识别类型

确定您要创建的内容类型：

步骤 2：创建文件夹

# 使用 slug 格式：小写、使用短横线、不含空格
mkdir -p docs/{section}/{category}/{slug}

# 示例
mkdir -p docs/todo/pending/user-auth-flow
mkdir -p docs/define/features/dark-mode
mkdir -p docs/rules/code/error-handling

步骤 3：复制模板

# 复制对应模板
cp docs/_templates/{type}.md docs/{path}/{slug}/{type}.md

# 示例
cp docs/_templates/task.md docs/todo/pending/user-auth-flow/task.md
cp docs/_templates/feature.md docs/define/features/dark-mode/feature.md
cp docs/_templates/rule.md docs/rules/code/error-handling/rule.md

步骤 4：填充内容

在模板中填写实际内容。具体必需章节请参阅各子技能文档。

步骤 5：添加信号

# 常用信号
echo '{"schema": "1.0", "created": "'$(date -Iseconds)'"}' > {folder}/.version

# 类型特定信号
echo "high" > docs/todo/pending/{task}/.priority
touch docs/rules/code/{rule}/.enforced_by

步骤 6：验证结构

# 验证文件夹是否包含必需文件
ls -la docs/{path}/{slug}/

# 任务示例预期输出：
# task.md
# .version
# .priority

模板概览

任务模板

# Task: {Title}

## Summary

{内容与目的}

## Objectives

- Objective 1
- Objective 2

## Acceptance Criteria

- [ ] Criterion 1
- [ ] Criterion 2

## Dependencies

{无或列表}

## Estimated Effort

{Size} ({time})

功能模板

# Feature: {Name}

## Summary

{功能说明}

## User Stories

As a {user}, I want to {action}, so that {benefit}.

## Scope

### In Scope

- Item 1

### Out of Scope

- Item 1

## Success Metrics

- Metric 1

定义模板

# {Name}

## Summary

{一段文字}

## Details

{完整说明}

## Examples

{示例}

## Related

- {Links}

规则模板

# Rule: {Name}

## Summary

{一句话概括}

## Rationale

{原因}

## The Rule

{MUST/SHOULD/MAY 表述}

## Examples

### Correct

{示例}

### Incorrect

{示例}

## Enforcement

{执行方式}

批量创建

一次性创建多个关联项：

#!/bin/bash
# create-feature-with-tasks.sh

FEATURE=$1

# 创建功能定义
mkdir -p docs/define/features/$FEATURE
cat > docs/define/features/$FEATURE/feature.md << EOF
# Feature: $(echo $FEATURE | tr '-' ' ' | sed 's/b(.)/u1/g')

## Summary

TODO: Add summary

## User Stories

As a user, I want to TODO, so that TODO.
EOF

# 创建初始任务
for task in "design" "implement" "test" "document"; do
  mkdir -p docs/todo/pending/${FEATURE}-${task}
  cat > docs/todo/pending/${FEATURE}-${task}/task.md << EOF
# Task: $(echo $FEATURE | tr '-' ' ' | sed 's/b(.)/u1/g') - $(echo $task | sed 's/b(.)/u1/g')

## Summary

${task^} the $FEATURE feature.

## Objectives

- TODO

## Acceptance Criteria

- [ ] TODO
EOF
  echo "medium" > docs/todo/pending/${FEATURE}-${task}/.priority
done

echo "Created feature: $FEATURE"
echo "Created tasks: ${FEATURE}-design, ${FEATURE}-implement, ${FEATURE}-test, ${FEATURE}-document"

使用方式：

./create-feature-with-tasks.sh dark-mode

命名规范

Slug 格式

所有文件夹名称均须采用 slug 格式：

良好命名示例

docs/todo/pending/add-steam-oauth
docs/define/features/dark-mode-toggle
docs/rules/code/no-implicit-any

不良命名示例

docs/todo/pending/Add Steam OAuth          # 含空格及大写字母
docs/define/features/dark_mode_toggle      # 含下划线
docs/rules/code/rule1                      # 缺乏描述性

校验

创建任意文档后，请执行以下检查：

检查必需文件

# 任务
test -f docs/todo/pending/{slug}/task.md || echo "MISSING: task.md"
test -f docs/todo/pending/{slug}/.priority || echo "MISSING: .priority"

# 功能
test -f docs/define/features/{slug}/feature.md || echo "MISSING: feature.md"
test -f docs/define/features/{slug}/mvp.md || echo "MISSING: mvp.md"

# 规则
test -f docs/rules/{category}/{slug}/rule.md || echo "MISSING: rule.md"
test -f docs/rules/{category}/{slug}/.enforced_by || echo "MISSING: .enforced_by"

检查必需章节

# 对任意 Markdown 文件，检查必需标题
file=$1
required=("## Summary" "## Objectives" "## Acceptance Criteria")

for section in "${required[@]}"; do
  grep -q "$section" "$file" || echo "MISSING: $section in $file"
done

常见创建模式

新功能流程

1. 创建功能定义
2. 创建 mvp.md 定义范围
3. 创建 phase_0.md 描述初始工作
4. 为 phase_0 创建任务

# 1. 功能文件夹
mkdir -p docs/define/features/search

# 2. 功能定义
cat > docs/define/features/search/feature.md << 'EOF'
# Feature: Global Search

## Summary
Fuzzy search across all content types.
EOF

# 3. MVP 范围
cat > docs/define/features/search/mvp.md << 'EOF'
# MVP: Global Search

## In MVP
- Phase 0 only

## Definition of Done
- Search returns results in <100ms
- Fuzzy matching works
EOF

# 4. Phase 0
cat > docs/define/features/search/phase_0.md << 'EOF'
# Phase 0: Basic Search

## Deliverables
- MiniSearch integration
- Global search component
EOF

# 5. 任务
mkdir -p docs/todo/pending/search-minisearch-setup
# ... 创建任务

新规则流程

1. 识别需标准化的模式
2. 创建规则文件夹
3. 编写含示例的规则
4. 配置执行机制
5. 向团队公告

# 1. 规则文件夹
mkdir -p docs/rules/code/async-await

# 2. 规则定义
cat > docs/rules/code/async-await/rule.md << 'EOF'
# Rule: Prefer async/await

## Summary
SHOULD use async/await over .then() chains.

## Rationale
Improved readability and error handling.

## The Rule
...
EOF

# 3. 示例
cat > docs/rules/code/async-await/examples.md << 'EOF'
# Examples
...
EOF

# 4. 执行配置
echo "eslint prefer-async-await" > docs/rules/code/async-await/.enforced_by

# 5. 配置 ESLint
# 编辑 .eslintrc.js

信号文件快速参考

创建检查清单

在最终确认任一新建文档前，请完成以下检查：

• 文件夹名符合 slug 格式
• 主文件已存在（如 task.md、feature.md 等）
• 已添加 .version 信号
• 必需章节均已存在
• 无残留的 TODO 占位符
• 所有链接有效
• 已检查拼写与语法
• 已交叉引用相关文档