代码规范 Skill

触发时机

• 用户要求写代码、实现功能、创建模块
• 创建或修改 temporal 工作流
• 添加新的 service、activities、models
• 任何代码开发工作开始前

写代码前必做

第一步：更新 item.md 文档

• 记录项目流程
• 记录主要类和函数（含输入输出）
• 记录 temporal/api 调用链路
• 这里面只记录主要函数的调用

第二步（仅新建文件时）：查阅目录结构

• 当需要新建文件时，先阅读 directory-structure.md（同目录下）
• 根据目录结构确定文件应该放置的位置

代码规范清单

1. 依赖注入

• ✅ 所有依赖注入必须在文件开头注入

2. 日志规范

• ✅ 必须使用 src/infrastructure 中的日志格式

3. 组件管理

• ✅ 常用组件（数据库连接等）在 src/infrastructure 中创建类统一管理

3.1 基础组件示例

数据库连接 位于 database_examples/ 目录：

Temporal/日志 位于 examples/ 目录：

使用步骤：

1. 复制对应示例文件到目标目录
2. 调整参数（从 config 读取）

4. Temporal/Modules 目录结构

• ✅ temporal/ 和 modules/ 必须包含：

temporal/
├── workflow/
├── activities/
├── service/
└── models/

• 每个workflow的activitie和service都要定义成类。

5. 环境变量与全局变量

• ✅ 必须在 config/ 文件夹中注入
• 环境变量中的常量和哪些放进.env文件的每次新增都得询问我

6. 函数命名

• ✅ 次要函数命名加 _ 前缀（如 _helper_function）
• ✅ 次要函数不记录在 item.md 中

7. 数据结构pydata的校验

• ✅ 不要每一种数据都定义数据结构，只有主要函数的需要定义，减少该部分代码量

item.md 文档格式

文档结构

# 项目名称

## 目录结构
[项目目录树，作为第一章]

---

## 项目流程
[整体流程图]

### Step 1: 步骤名称
[步骤说明表格]

### Step 2: 步骤名称
[步骤说明表格]

#### 子流程/节点执行顺序
[子流程表格]

#### 内部服务调用
[服务调用表格]

---

## 数据模型
[模型索引表]

---

## 代码位置索引
[代码位置索引表]

流程步骤表格格式

每个流程步骤使用表格标注类/方法/输入输出/文件位置/错误处理：

### Step N: 步骤名称

| 项目 | 说明 |
|------|------|
| **Workflow** | `WorkflowClass` - src/temporal/workflow.py |
| **Activity** | `activity_name()` - src/temporal/activities.py |
| **Agent** | `AgentClass` - src/langgraph/agent.py |
| **Graph** | src/langgraph/graph.py |
| **输入** | `InputModel` - src/temporal/models.py |
| **输出** | `OutputModel` - src/temporal/models.py |
| **功能** | 功能描述 |
| **错误处理** | 错误类型 → 处理策略 (最大重试次数) |
| **执行条件** | 条件说明（可选） |

执行检查

在开始编码前，按以下顺序确认：

1. [ ] item.md 已更新
2. [ ] item.md 目录结构作为第一章
3. [ ] item.md 项目流程每步标注类/方法/输入输出/文件位置/错误处理
4. [ ] 依赖注入位置正确
5. [ ] 日志使用正确格式
6. [ ] 目录结构符合规范
7. [ ] 环境变量在 config 中
8. [ ] 函数命名符合规范
9. [ ] 类型标注符合规范（固定类型指向 models 文件，非固定类型在 item.md 定义）
10. [ ] 错误处理策略已在 item.md 标注
11. [ ] 代码位置索引已更新