code-standards
📖 技能介绍
name: code-standards description: 代码规范检查清单。当用户要求写代码、创建新文件、实现功能、添加模块、修改代码结构、创建 temporal 工作流、或进行任何代码开发工作时，必须先调用此 skill 确保遵循规范。
代码规范 Skill
触发时机
- 用户要求写代码、实现功能、创建模块
- 创建或修改 temporal 工作流
- 添加新的 service、activities、models
- 任何代码开发工作开始前
写代码前必做
第一步：更新 item.md 文档 - 记录项目流程 - 记录主要类和函数（含输入输出） - 记录 temporal/api 调用链路 - 这里面只记录主要函数的调用
第二步（仅新建文件时）：查阅目录结构
- 当需要新建文件时，先阅读 directory-structure.md（同目录下）
- 根据目录结构确定文件应该放置的位置
代码规范清单
1. 依赖注入
- ✅ 所有依赖注入必须在文件开头注入
2. 日志规范
- ✅ 必须使用
src/infrastructure中的日志格式
3. 组件管理
- ✅ 常用组件（数据库连接等）在
src/infrastructure中创建类统一管理
3.1 基础组件示例
数据库连接 位于 database_examples/ 目录：
| 数据库 | 示例文件 | 使用场景 |
|---|---|---|
| MySQL | mysql_example.py |
关系型数据存储、事务性操作 |
| PostgreSQL | postgresql_example.py |
关系型数据、JSONB 字段支持 |
| MongoDB | mongodb_example.py |
文档型数据、灵活 Schema、Decimal 编解码 |
| Redis | redis_example.py |
缓存、分布式锁、消息队列 |
| Presto/Trino | presto_example.py |
大数据查询、OLAP、流式查询 |
Temporal/日志 位于 examples/ 目录：
| 示例文件 | 使用场景 |
|---|---|
temporal_client_example.py |
客户端单例管理、工作流启动/查询/取消 |
logger_example.py |
Loguru 日志配置（控制台+文件、轮转、压缩） |
使用步骤：
1. 复制对应示例文件到目标目录
2. 调整参数（从 config 读取）
4. Temporal/Modules 目录结构
- ✅
temporal/和modules/必须包含：
temporal/
├── workflow/
├── activities/
├── service/
└── models/
- 每个workflow的activitie和service都要定义成类。
5. 环境变量与全局变量
- ✅ 必须在
config/文件夹中注入 - 环境变量中的常量和哪些放进.env文件的每次新增都得询问我
6. 函数命名
- ✅ 次要函数命名加
_前缀（如_helper_function）想要更强大的技能插件，就来小葱技能站7w4.net看看吧。
- ✅ 次要函数不记录在 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. [ ] 代码位置索引已更新
🤖 AI 评测
这个 Skill 质量不错，提供了完整的代码规范和大量可直接复用的模板示例，能帮助团队保持代码一致性。规范覆盖面广，文档格式清晰，但规则较多且部分内容有重复，理解和执行起来可能需要一定学习成本。缺少测试相关指导是明显的短板。总体而言，这是一个实用性强但仍有优化空间的代码规范工具包。
