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