---
name: 0008-execution-logging
description: 执行与记录，编写代码并实时记录在 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: 首句申明
```markdown
## 首句申明

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

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

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

#### 步骤 2: 编写代码
```markdown
## 代码编写

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

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

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

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

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

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

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

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

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

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

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

#### 步骤 4: 记录最终决策
```markdown
## 最终决策

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

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

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

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

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

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

#### 步骤 5: 记录复现步骤
```markdown
## 复现步骤

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

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

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

#### 步骤 6: 创建 Session Log
```markdown
---
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
```markdown
### 🗣️ 会话记录 (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 示例
```markdown
## 首句申明

### 现状 (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 示例
```markdown
## 执行过程

开始编写代码...

创建了 UserImportServiceImpl.java。

创建了 UserImportController.java。

完成了。
```

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

## 相关文档 (Related Documents)

- [工作流提示词](../prompts/03-创建工作流提示词.md#阶段-5-执行与记录-execution-logging)
- [上下文锚定技能](./0007-context-anchoring.md)
- [变更记录与归档技能](./0009-changelog-archiving.md)
- [Session 模板](../prompts/03-创建工作流提示词.md#43-session-logs-模板-会话上下文)