502 lines
12 KiB
Markdown
502 lines
12 KiB
Markdown
---
|
||
name: 0003-setup-information-architecture
|
||
description: 落地信息架构，创建标准目录结构和模板文件
|
||
---
|
||
|
||
# 技能：落地信息架构 (Setup Information Architecture)
|
||
|
||
## 元数据 (Metadata)
|
||
|
||
- **name**: setup-information-architecture
|
||
- **description**: 落地信息架构，创建标准目录结构和模板文件
|
||
- **version**: 1.0.0
|
||
- **author**: SSOT Architect
|
||
- **lastUpdated**: 2026-01-15
|
||
|
||
## 触发与定位 (Triggers & Scope)
|
||
|
||
### 触发条件 (Triggers)
|
||
当以下情况发生时，AI 应当"觉醒"本技能：
|
||
|
||
1. **SSOT Hub 完成**: 完成建立真源中心后
|
||
2. **目录结构缺失**: 检测到 `docs/` 目录缺少标准子目录
|
||
3. **模板文件缺失**: 检测到模板文件不存在
|
||
4. **新项目初始化**: 用户要求初始化新项目的文档结构
|
||
5. **工作流阶段 3**: 用户进入工作流的"落地信息架构"阶段
|
||
|
||
### 定位范围 (Scope)
|
||
- **适用模块**: 所有 Datai 项目模块
|
||
- **影响目录**: `docs/` 及其子目录
|
||
- **影响文件**: 所有模板文件
|
||
- **相关技能**: skill-establish-ssot-hub, skill-inject-templates
|
||
|
||
## 核心指令集 (Instructions)
|
||
|
||
### 架构约束 (Architecture Constraints)
|
||
|
||
1. **必须创建的标准目录结构**:
|
||
```
|
||
docs/
|
||
├── index.md # 单一真源入口
|
||
├── requirements/ # 需求文档
|
||
├── design/ # 系统设计
|
||
├── decisions/ # 架构决策
|
||
│ └── adr/ # ADR 专用目录
|
||
├── prompts/ # 提示词资产
|
||
├── sessions/ # AI 会话快照
|
||
├── retros/ # 迭代复盘
|
||
├── changelog/ # 变更记录
|
||
└── skills/ # 技能文档
|
||
```
|
||
|
||
2. **必须创建的模板文件**:
|
||
- `docs/decisions/adr/0000-template.md` - ADR 模板
|
||
- `docs/prompts/0000-template.md` - Prompt 模板
|
||
- `docs/sessions/YYYYMMDD-template.md` - Session 模板
|
||
- `docs/retros/YYYYMMDD-template.md` - Retro 模板
|
||
|
||
3. **目录命名规范**:
|
||
- 使用小写字母
|
||
- 使用连字符分隔单词（如 `adr`）
|
||
- 使用复数形式（如 `requirements`）
|
||
|
||
### 业务逻辑 SOP (Business Logic SOP)
|
||
|
||
#### 步骤 1: 检查现有目录结构
|
||
```bash
|
||
# 检查 docs/ 目录是否存在
|
||
if [ ! -d "docs" ]; then
|
||
echo "警告: docs/ 目录不存在，需要创建"
|
||
fi
|
||
|
||
# 检查各个子目录是否存在
|
||
required_dirs=("requirements" "design" "decisions" "prompts" "sessions" "retros" "changelog" "skills")
|
||
for dir in "${required_dirs[@]}"; do
|
||
if [ ! -d "docs/$dir" ]; then
|
||
echo "警告: docs/$dir/ 目录不存在"
|
||
fi
|
||
done
|
||
```
|
||
|
||
#### 步骤 2: 创建缺失的目录
|
||
```bash
|
||
# 创建标准目录结构
|
||
mkdir -p docs/requirements
|
||
mkdir -p docs/design
|
||
mkdir -p docs/decisions/adr
|
||
mkdir -p docs/prompts
|
||
mkdir -p docs/sessions
|
||
mkdir -p docs/retros
|
||
mkdir -p docs/changelog
|
||
mkdir -p docs/skills
|
||
```
|
||
|
||
#### 步骤 3: 创建 ADR 模板
|
||
```markdown
|
||
---
|
||
name: ADR-0000-template
|
||
description: 架构决策记录模板
|
||
---
|
||
|
||
# [决策标题]
|
||
|
||
## 元数据 (Metadata)
|
||
|
||
- **Status**: [Draft | Accepted | Deprecated]
|
||
- **Date**: YYYY-MM-DD
|
||
- **Decision Maker**: [决策者姓名]
|
||
- **Related Requirements**: [相关需求链接]
|
||
|
||
## 背景 (Context)
|
||
|
||
### 问题描述
|
||
[为什么要做这个决策？]
|
||
|
||
### 当前状态
|
||
[当前系统状态]
|
||
|
||
### 问题影响
|
||
[问题对系统的影响]
|
||
|
||
## 决策 (Decision)
|
||
|
||
### 决策内容
|
||
[我们决定做什么？]
|
||
|
||
### 技术方案
|
||
[详细的技术方案]
|
||
|
||
### 实施计划
|
||
[实施步骤和时间表]
|
||
|
||
## 后果 (Consequences)
|
||
|
||
### 正面影响
|
||
[好的后果]
|
||
|
||
### 负面影响
|
||
[坏的后果和 Trade-offs]
|
||
|
||
### 风险评估
|
||
[潜在风险和缓解措施]
|
||
|
||
## 合规性验证 (Compliance)
|
||
|
||
### 验证标准
|
||
[如何验证决策已被执行？]
|
||
|
||
### 验证方法
|
||
[验证的具体方法]
|
||
|
||
### 验证结果
|
||
[验证结果记录]
|
||
|
||
## 相关文档 (Related Documents)
|
||
|
||
- [需求文档](../../requirements/REQ-XXX.md)
|
||
- [设计文档](../../design/DES-XXX.md)
|
||
- [其他 ADR](./ADR-XXX.md)
|
||
|
||
## 变更历史 (Change History)
|
||
|
||
| 日期 | 版本 | 变更内容 | 变更人 |
|
||
|------|------|----------|--------|
|
||
| YYYY-MM-DD | 1.0.0 | 初始版本 | [姓名] |
|
||
```
|
||
|
||
#### 步骤 4: 创建 Prompt 模板
|
||
```markdown
|
||
---
|
||
name: PROMPT-0000-template
|
||
description: 提示词资产模板
|
||
version: 1.0.0
|
||
---
|
||
|
||
# 提示词: [提示词名称]
|
||
|
||
## 元数据 (Metadata)
|
||
|
||
- **name**: [提示词名称]
|
||
- **description**: [该提示词解决什么具体问题？]
|
||
- **version**: [版本号]
|
||
- **author**: [作者]
|
||
- **lastUpdated**: [最后更新日期]
|
||
|
||
## 目标 (Goal)
|
||
|
||
[该提示词解决什么具体问题？]
|
||
|
||
## 上下文链接 (Context Links)
|
||
|
||
### 必须引用的文档
|
||
- [需求文档](../../requirements/REQ-XXX.md)
|
||
- [设计文档](../../design/DES-XXX.md)
|
||
- [ADR 文档](../../decisions/adr/ADR-XXX.md)
|
||
|
||
### 参考文档
|
||
- [其他相关文档](../../docs/XXX.md)
|
||
|
||
## 输入变量 (Inputs)
|
||
|
||
| 变量名 | 类型 | 必填 | 说明 | 示例 |
|
||
|--------|------|------|------|------|
|
||
| [变量名] | [类型] | [是/否] | [说明] | [示例] |
|
||
|
||
## 提示词内容 (Prompt Content)
|
||
|
||
```markdown
|
||
[实际的提示词内容]
|
||
```
|
||
|
||
## 输出定义 (Output Definition)
|
||
|
||
### 输出格式
|
||
[期望的输出格式：JSON/Markdown/Code]
|
||
|
||
### 输出结构
|
||
[详细的输出结构说明]
|
||
|
||
### 输出示例
|
||
```json
|
||
[输出示例]
|
||
```
|
||
|
||
## 版本历史 (Version History)
|
||
|
||
| 版本 | 日期 | 变更内容 | 变更人 |
|
||
|------|------|----------|--------|
|
||
| 1.0.0 | YYYY-MM-DD | 初始版本 | [姓名] |
|
||
```
|
||
|
||
#### 步骤 5: 创建 Session 模板
|
||
```markdown
|
||
---
|
||
name: SESSION-YYYYMMDD-template
|
||
description: AI 会话快照模板
|
||
---
|
||
|
||
# 会话记录: [任务名称]
|
||
|
||
## 元数据 (Metadata)
|
||
|
||
- **Date**: YYYY-MM-DD
|
||
- **Session ID**: [会话ID]
|
||
- **Trigger**: [触发本次会话的需求或 Bug ID]
|
||
- **Used Prompts**: [链接到使用的 Prompt 文件]
|
||
- **Outcome**: [最终产生的代码变更 Commit Hash]
|
||
|
||
## 触发原因 (Trigger)
|
||
|
||
[触发本次会话的需求或 Bug 描述]
|
||
|
||
## 使用的提示词 (Used Prompts)
|
||
|
||
- [Prompt-001](../prompts/PROMPT-001.md) - [提示词描述]
|
||
- [Prompt-002](../prompts/PROMPT-002.md) - [提示词描述]
|
||
|
||
## 上下文锚定 (Context Anchoring)
|
||
|
||
### 现状 (Current State)
|
||
[当前系统状态]
|
||
|
||
### 目标 (Target State)
|
||
[期望达到的目标]
|
||
|
||
### 引用的上下文文件
|
||
- [文件1](../../path/to/file1.md) - [说明]
|
||
- [文件2](../../path/to/file2.md) - [说明]
|
||
|
||
## 执行过程 (Execution Process)
|
||
|
||
### 步骤 1: [步骤名称]
|
||
[执行步骤描述]
|
||
|
||
### 步骤 2: [步骤名称]
|
||
[执行步骤描述]
|
||
|
||
### AI 质疑与替代方案
|
||
[记录 AI 的质疑、替代方案]
|
||
|
||
### 最终决策
|
||
[最终采用的方案和理由]
|
||
|
||
## 代码变更 (Code Changes)
|
||
|
||
### 变更文件列表
|
||
- [文件1](../../path/to/file1.java) - [变更说明]
|
||
- [文件2](../../path/to/file2.java) - [变更说明]
|
||
|
||
### Commit Hash
|
||
[Commit Hash: abc123def456]
|
||
|
||
### Commit Message
|
||
```
|
||
[Commit Message]
|
||
```
|
||
|
||
## 结果 (Outcome)
|
||
|
||
### 成功指标
|
||
[达成的成功指标]
|
||
|
||
### 未达成指标
|
||
[未达成的指标和原因]
|
||
|
||
### 经验教训
|
||
[本次会话的经验教训]
|
||
|
||
## 相关文档 (Related Documents)
|
||
|
||
- [需求文档](../../requirements/REQ-XXX.md)
|
||
- [ADR 文档](../../decisions/adr/ADR-XXX.md)
|
||
- [复盘文档](../retros/YYYYMMDD-Review.md)
|
||
```
|
||
|
||
#### 步骤 6: 创建 Retro 模板
|
||
```markdown
|
||
---
|
||
name: RETRO-YYYYMMDD-template
|
||
description: 迭代复盘模板
|
||
---
|
||
|
||
# 迭代复盘: [复盘名称]
|
||
|
||
## 元数据 (Metadata)
|
||
|
||
- **Date**: YYYY-MM-DD
|
||
- **Review Type**: [Sprint Review/Feature Review/Process Review]
|
||
- **Review Period**: [复盘周期]
|
||
- **Participants**: [参与者]
|
||
|
||
## 目标 vs 结果指标对比 (Goal vs Result Metrics)
|
||
|
||
### 目标指标
|
||
| 指标名称 | 目标值 | 实际值 | 达成率 |
|
||
|----------|--------|--------|--------|
|
||
| [指标1] | [目标值] | [实际值] | [达成率] |
|
||
| [指标2] | [目标值] | [实际值] | [达成率] |
|
||
|
||
### 结果分析
|
||
[目标与结果的差异分析]
|
||
|
||
## 3 条有效 Prompt 模式 (3 Effective Prompt Patterns)
|
||
|
||
### 模式 1: [模式名称]
|
||
[描述该模式的有效性]
|
||
- **适用场景**: [适用场景]
|
||
- **示例**: [示例]
|
||
|
||
### 模式 2: [模式名称]
|
||
[描述该模式的有效性]
|
||
- **适用场景**: [适用场景]
|
||
- **示例**: [示例]
|
||
|
||
### 模式 3: [模式名称]
|
||
[描述该模式的有效性]
|
||
- **适用场景**: [适用场景]
|
||
- **示例**: [示例]
|
||
|
||
## 3 条踩坑与改进 (3 Pitfalls and Improvements)
|
||
|
||
### 踩坑 1: [问题描述]
|
||
- **问题描述**: [详细描述问题]
|
||
- **影响**: [问题的影响]
|
||
- **改进措施**: [如何改进]
|
||
- **Action Item**: [具体行动项]
|
||
|
||
### 踩坑 2: [问题描述]
|
||
- **问题描述**: [详细描述问题]
|
||
- **影响**: [问题的影响]
|
||
- **改进措施**: [如何改进]
|
||
- **Action Item**: [具体行动项]
|
||
|
||
### 踩坑 3: [问题描述]
|
||
- **问题描述**: [详细描述问题]
|
||
- **影响**: [问题的影响]
|
||
- **改进措施**: [如何改进]
|
||
- **Action Item**: [具体行动项]
|
||
|
||
## 模板更新记录 (Template Updates)
|
||
|
||
### Prompt 模板更新
|
||
- [Prompt-001](../prompts/PROMPT-001.md): [更新内容]
|
||
- [Prompt-002](../prompts/PROMPT-002.md): [更新内容]
|
||
|
||
### ADR 模板更新
|
||
- [ADR-001](../decisions/adr/ADR-001.md): [更新内容]
|
||
|
||
### Session 模板更新
|
||
- [Session-YYYYMMDD](../sessions/YYYYMMDD-TaskName.md): [更新内容]
|
||
|
||
## 技能练习记录 (Skill Practice)
|
||
|
||
### 练习的技能
|
||
- [技能1](../skills/0001-skill-name.md): [练习内容]
|
||
- [技能2](../skills/0002-skill-name.md): [练习内容]
|
||
|
||
### 技能提升
|
||
[技能提升的总结]
|
||
|
||
## 流程改进建议 (Process Improvement)
|
||
|
||
### 建议改进的流程
|
||
1. [改进建议1]
|
||
2. [改进建议2]
|
||
3. [改进建议3]
|
||
|
||
### 需要更新的文档
|
||
- [CONTRIBUTING.md](../../CONTRIBUTING.md): [更新内容]
|
||
- [README.md](../../README.md): [更新内容]
|
||
|
||
## 相关文档 (Related Documents)
|
||
|
||
- [会话记录](../sessions/YYYYMMDD-TaskName.md)
|
||
- [需求文档](../../requirements/REQ-XXX.md)
|
||
- [ADR 文档](../../decisions/adr/ADR-XXX.md)
|
||
```
|
||
|
||
### 工具调用 (Tool Usage)
|
||
|
||
1. **目录检查工具**:
|
||
- 使用 `LS` 工具检查 `docs/` 目录结构
|
||
- 列出所有子目录
|
||
|
||
2. **文件检查工具**:
|
||
- 使用 `Read` 工具检查模板文件是否存在
|
||
- 读取现有模板文件内容
|
||
|
||
3. **目录创建工具**:
|
||
- 使用 `RunCommand` 执行 `mkdir -p` 命令创建目录
|
||
|
||
4. **文件创建工具**:
|
||
- 使用 `Write` 工具创建模板文件
|
||
- 确保文件路径正确
|
||
|
||
## 错误陷阱与验证 (Anti-Patterns & Checklist)
|
||
|
||
### 常见错误 (Anti-Patterns)
|
||
|
||
1. **错误**: 目录命名不规范（使用大写或下划线）
|
||
- **后果**: 目录结构不一致，难以维护
|
||
- **修正**: 使用小写字母和连字符
|
||
|
||
2. **错误**: 模板文件缺少必要的元数据
|
||
- **后果**: 无法追踪文档版本和作者
|
||
- **修正**: 确保所有模板包含完整的元数据
|
||
|
||
3. **错误**: 模板内容过于简单
|
||
- **后果**: 生成的文档质量低
|
||
- **修正**: 提供详细的模板和示例
|
||
|
||
4. **错误**: 忘记创建 ADR 子目录
|
||
- **后果**: ADR 文档组织混乱
|
||
- **修正**: 必须创建 `docs/decisions/adr/` 目录
|
||
|
||
5. **错误**: 模板文件命名不一致
|
||
- **后果**: 难以识别和使用模板
|
||
- **修正**: 使用统一的命名规范（如 `0000-template.md`）
|
||
|
||
### 验收清单 (Acceptance Checklist)
|
||
|
||
- [ ] 所有标准目录已创建
|
||
- [ ] 所有模板文件已创建
|
||
- [ ] 目录命名符合规范
|
||
- [ ] 模板文件命名符合规范
|
||
- [ ] ADR 模板包含所有必需字段
|
||
- [ ] Prompt 模板包含所有必需字段
|
||
- [ ] Session 模板包含所有必需字段
|
||
- [ ] Retro 模板包含所有必需字段
|
||
- [ ] 所有模板包含元数据
|
||
- [ ] 所有模板包含示例
|
||
|
||
### Correct vs Incorrect 对比
|
||
|
||
#### Correct 示例
|
||
```bash
|
||
mkdir -p docs/requirements
|
||
mkdir -p docs/design
|
||
mkdir -p docs/decisions/adr
|
||
mkdir -p docs/prompts
|
||
mkdir -p docs/sessions
|
||
mkdir -p docs/retros
|
||
mkdir -p docs/changelog
|
||
mkdir -p docs/skills
|
||
```
|
||
|
||
#### Incorrect 示例
|
||
```bash
|
||
mkdir -p docs/Requirements
|
||
mkdir -p docs/Design
|
||
mkdir -p docs/Decisions
|
||
mkdir -p docs/Prompts
|
||
```
|
||
|
||
**问题**: 目录名称使用大写字母，不符合命名规范。
|
||
|
||
## 相关文档 (Related Documents)
|
||
|
||
- [工作流提示词](../prompts/03-创建工作流提示词.md#phase-3-落地信息架构-information-architecture)
|
||
- [SSOT Hub 技能](./0002-establish-ssot-hub.md)
|
||
- [注入模板技能](./0004-inject-templates.md)
|
||
- [目录结构规范](../prompts/03-创建工作流提示词.md#4-目录与模板规范)
|