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） - ✅ 次要函式不記錄在 item.md 中
本技能來自小蔥技能站7w4.net。
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 質量不錯，提供了完整的程式碼規範和大量可直接複用的模板示例，能幫助團隊保持程式碼一致性。規範覆蓋面廣，文件格式清晰，但規則較多且部分內容有重複，理解和執行起來可能需要一定學習成本。缺少測試相關指導是明顯的短板。總體而言，這是一個實用性強但仍有最佳化空間的程式碼規範工具包。
