datai/docs/archive/skill/0008-execution-logging.md

name	description
0008-execution-logging	执行与记录，编写代码并实时记录在 docs/sessions/

技能：执行与记录 (Execution & Logging)

元数据 (Metadata)

• name: execution-logging
• description: 执行与记录，编写代码并实时记录在 docs/sessions/
• version: 1.0.0
• author: SSOT Architect
• lastUpdated: 2026-01-15

触发与定位 (Triggers & Scope)

触发条件 (Triggers)

当以下情况发生时，AI 应当"觉醒"本技能：

1. 上下文锚定完成: 完成上下文分析后，开始编写代码
2. 代码生成: 需要生成特定功能的代码
3. 代码修改: 需要修改现有代码
4. 代码重构: 需要重构现有代码
5. 工作流阶段 5: 用户进入工作流的"执行与记录"阶段

定位范围 (Scope)

• 适用模块: 所有 Datai 项目模块
• 影响文件: 源代码文件、docs/sessions/YYYYMMDD-TaskName.md
• 相关技能: skill-context-anchoring, skill-changelog-archiving

核心指令集 (Instructions)

架构约束 (Architecture Constraints)

1. Session Log 必须包含:

   • Trigger: 触发本次会话的需求或 Bug ID
   • Used Prompts: 链接到使用了 docs/prompts/ 下的哪个文件
   • Outcome: 最终产生了哪些代码变更（Commit Hash）
   • 记录不仅仅是"聊天记录"，而是"状态恢复点"

2. 首句申明规则:

   • 明确当前"现状"与"目标"
   • 说明要实现的功能
   • 说明参考的代码模式

3. 代码生成规则:

   • 基于阶段 4 的锚定生成代码
   • 确保风格一致
   • 遵循现有代码规范

4. 实时记录规则:

   • 记录 AI 的质疑
   • 记录替代方案
   • 记录最终决策
   • 记录复现步骤

业务逻辑 SOP (Business Logic SOP)

步骤 1: 首句申明

## 首句申明

### 现状 (Current State)
[当前系统状态]

### 目标 (Target State)
[期望达到的目标]

### 参考的代码模式
我将参考 [类名](../../path/to/Class.java) 的模式进行开发。

步骤 2: 编写代码

## 代码编写

### 步骤 1: [步骤名称]
[编写代码的步骤描述]

### 步骤 2: [步骤名称]
[编写代码的步骤描述]

### 步骤 3: [步骤名称]
[编写代码的步骤描述]

步骤 3: 记录 AI 质疑与替代方案

## AI 质疑与替代方案

### 质疑 1: [质疑内容]
**质疑**: [AI 提出的质疑]

**分析**: [质疑的分析]

**决策**: [最终的决策]

### 替代方案 1: [方案名称]
**方案描述**: [替代方案的描述]

**优点**: [方案的优点]

**缺点**: [方案的缺点]

**选择结果**: [是否选择该方案]

步骤 4: 记录最终决策

## 最终决策

### 决策 1: [决策内容]
**决策**: [最终的决策]

**理由**: [决策的理由]

**影响**: [决策的影响]

### 决策 2: [决策内容]
**决策**: [最终的决策]

**理由**: [决策的理由]

**影响**: [决策的影响]

步骤 5: 记录复现步骤

## 复现步骤

### 步骤 1: [步骤名称]
1. [操作步骤]
2. [操作步骤]
3. [操作步骤]

### 步骤 2: [步骤名称]
1. [操作步骤]
2. [操作步骤]
3. [操作步骤]

### 验证方法
[如何验证代码是否正确]

步骤 6: 创建 Session Log

---
name: SESSION-YYYYMMDD-TaskName
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.java) - [说明]
- [文件2](../../path/to/file2.java) - [说明]

## 执行过程 (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)

### 成功指标
| 指标 | 目标值 | 实际值 | 状态 |
|------|--------|--------|------|
| [指标1] | [目标值] | [实际值] | [状态] |
| [指标2] | [目标值] | [实际值] | [状态] |

### 未达成指标
[未达成的指标和原因]

### 经验教训
[本次会话的经验教训]

## 相关文档 (Related Documents)

- [需求文档](../../requirements/REQ-XXX.md)
- [ADR 文档](../../decisions/adr/ADR-XXX.md)
- [复盘文档](../retros/YYYYMMDD-Review.md)

步骤 7: 更新 docs/index.md

### 🗣️ 会话记录 (Sessions)
| 文档 | 触发 | 结果 | 日期 |
|------|------|------|------|
| [20260115-TaskName](sessions/20260115-TaskName.md) | REQ-001 | Commit: abc123 | 2026-01-15 |

工具调用 (Tool Usage)

1. 代码编写工具:

   • 使用 Write 工具创建新文件
   • 使用 SearchReplace 工具修改现有文件
   • 使用 DeleteFile 工具删除文件

2. 代码验证工具:

   • 使用 GetDiagnostics 工具检查代码错误
   • 使用 RunCommand 工具运行测试

3. 文档记录工具:

   • 使用 Write 工具创建 Session Log
   • 使用 Read 工具读取现有 Session Log
   • 使用 SearchReplace 工具更新 Session Log

4. 索引更新工具:

   • 使用 Read 工具读取 docs/index.md
   • 使用 SearchReplace 工具更新索引

错误陷阱与验证 (Anti-Patterns & Checklist)

常见错误 (Anti-Patterns)

1. 错误: 不记录 AI 质疑和替代方案

   • 后果: 无法追溯决策过程，难以复现
   • 修正: 必须详细记录 AI 的质疑、替代方案和最终决策

2. 错误: Session Log 只是聊天记录

   • 后果: 无法作为"状态恢复点"
   • 修正: Session Log 必须包含现状、目标、上下文、决策、结果等完整信息

3. 错误: 不记录复现步骤

   • 后果: 无法复现代码生成过程
   • 修正: 必须详细记录复现步骤和验证方法

4. 错误: 代码风格不一致

   • 后果: 代码质量低，难以维护
   • 修正: 必须基于上下文锚定的参考模式生成代码

5. 错误: 忘记更新 docs/index.md

   • 后果: 产生孤儿文件，违反 SSOT 原则
   • 修正: 创建 Session Log 后必须更新索引

验收清单 (Acceptance Checklist)

• 首句申明已完成
• 代码已编写
• AI 质疑已记录
• 替代方案已记录
• 最终决策已记录
• 复现步骤已记录
• Session Log 已创建
• Commit Hash 已记录
• 成功指标已记录
• docs/index.md 已更新
• 相关文档已链接

Correct vs Incorrect 对比

Correct 示例

## 首句申明

### 现状 (Current State)
当前系统没有用户批量导入功能。

### 目标 (Target State)
实现用户批量导入功能，支持 CSV 格式，单次最多导入 1000 条记录。

### 参考的代码模式
我将参考 [ProductImportServiceImpl](../../path/to/ProductImportServiceImpl.java) 的模式进行开发。

## AI 质疑与替代方案

### 质疑 1: 是否需要支持 Excel 格式？
**质疑**: 用户可能需要导入 Excel 格式的文件。

**分析**: Excel 格式更复杂，需要额外的依赖库。

**决策**: 暂不支持 Excel 格式，先实现 CSV 格式，后续根据需求扩展。

### 替代方案 1: 使用 Apache POI 处理 Excel
**方案描述**: 使用 Apache POI 库处理 Excel 文件。

**优点**: 功能强大，支持多种 Excel 格式。

**缺点**: 依赖库较大，增加项目复杂度。

**选择结果**: 不选择该方案。

## 复现步骤

### 步骤 1: 创建导入服务类
1. 创建 UserImportServiceImpl.java
2. 实现 importUsers 方法
3. 添加 @Transactional 注解

### 步骤 2: 创建导入控制器
1. 创建 UserImportController.java
2. 添加 importUsers 接口
3. 添加文件上传处理

### 验证方法
1. 编写单元测试
2. 使用 Postman 测试接口
3. 导入测试 CSV 文件

Incorrect 示例

## 执行过程

开始编写代码...

创建了 UserImportServiceImpl.java。

创建了 UserImportController.java。

完成了。

问题: 没有首句申明，没有记录 AI 质疑和替代方案，没有记录复现步骤。

相关文档 (Related Documents)

• 工作流提示词
• 上下文锚定技能
• 变更记录与归档技能
• Session 模板