373 lines
9.3 KiB
Markdown
373 lines
9.3 KiB
Markdown
---
|
||
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-模板-会话上下文)
|