---
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-目录与模板规范)
