datai/datai-scenes/datai-scene-salesforce/docs/skill/0003-setup-information-architecture.md

name	description
0003-setup-information-architecture	落地信息架构，创建标准目录结构和模板文件

技能：落地信息架构 (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: 检查现有目录结构

# 检查 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: 创建缺失的目录

# 创建标准目录结构
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 模板

---
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 模板

---
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]

输出结构

[详细的输出结构说明]

输出示例

[输出示例]

版本历史 (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 模板

---
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 示例

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 示例

mkdir -p docs/Requirements
mkdir -p docs/Design
mkdir -p docs/Decisions
mkdir -p docs/Prompts

问题: 目录名称使用大写字母，不符合命名规范。

相关文档 (Related Documents)

• 工作流提示词
• SSOT Hub 技能
• 注入模板技能
• 目录结构规范