Code Organizer

👤 Puig 📦 v1.1.0 ⭐ 4.4 ⬇️ 827 下載

💻 開發程式設計免費

📖 技能介紹

Code Organizer - 程式碼整理與專案重構技能

概述

本技能用於對 Python 專案進行系統性整理和重構（預設通用風格，根據具體專案型別自動適配）重要原則：始終先生成整理建議，等待使用者批准後再執行任何檔案修改

⚠️ 避免過度工程化 - 核心約束

整理/重構到最佳實踐。所有最佳化措施均由使用者主動選擇，絕不預設執行

🔄 兩輪確認流程（必須嚴格執行）

每次執行整理任務前，必須經過兩輪使用者確認，不可跳過：

第一輪：策略選擇

掃描專案，評估規模（檔案數、模組數、專案型別）
根據評估結果，向用戶展示

可選策略列表

並給出推薦：

策略級別	適用場景	包含的整理措施
輕量清理	單指令碼、實驗性程式碼、臨時專案	無用程式碼清理、空目錄刪除、明顯命名問題修復 + 簡要文件
標準整理	小型工具、資料處理管道、原型專案	輕量清理 + 命名規範 + import 排序 + 程式碼格式 + 型別標註 + 規範註釋 + 標準文件
深度重構	可釋出的小庫、API 服務、完整 pipeline	標準整理 + 目錄結構重組 + src layout + init.py + 配置引數化 + 測試覆蓋 + 分層架構 + 詳細文件
全面重構	團隊專案、商業產品級應用	深度重構 + DDD 設計 + 完整測試套件 + pyproject.toml + 完整文件 + 程式碼質量檢查

向用戶說明推薦級別及理由，等待使用者確認或調整策略級別

第二輪：方案確認

基於使用者選擇的策略級別，生成詳細的整理方案，包括：
具體的目錄結構調整（如涉及）
每個需要修改的檔案及修改型別
預計可移除的無用程式碼/依賴
新增的檔案或配置
等待使用者明確確認後方可開始執行

判斷原則：

對於深度學習實驗/資料處理原型專案：如果核心是跑通流程而非工程化，優先推薦輕量或標準策略
使用者的策略選擇是最終決定，推薦僅供參考
任何超出使用者選擇策略範圍的最佳化，都不執行

工作流程

⚠️ 重要：防中斷架構設計

核心原則：使用並行子代理拆分任務，避免單會話超時導致的中斷 對於複雜專案重構（超過個檔案需要修改），必須採用以下模式：

# 錯誤做法：序列執行所有操作
for file in files_to_modify:
 read(file) # 阻塞等待
 edit(file) # 阻塞等待

# 正確做法：並行子代理 + 進度持久化
phases = [
 {"id": "phase-a", "task": "建立目錄結構"},
 {"id": "phase-b", "task": "移動檔案到對應目錄"},
 {"id": "phase-c", "task": "更新所有 import 路徑"},
 {"id": "phase-d", "task": "統一變數命名和型別提示"},
 {"id": "phase-e", "task": "生成三個文件檔案"}
]

for phase in phases:
 spawn_sub_agent(phase["id"], phase["task"]) # 並行啟動

Phase 1: 掃描與策略選擇（第一輪確認）

由主會話執行，輕量級操作

掃描專案 - 瞭解當前目錄結構、程式碼規模、模組依賴關係
使用 exec 或 background=true 模式進行耗時操作（如 robocopy, tree）

 # 推薦：後臺執行長時間任務
 cmd /c "robocopy E:\\LPR E:\\LPR_backup /MIR" > backup.log 2>&1 &

評估專案概況 - 統計以下資訊：
檔案數量、模組數量、專案型別（深度學習/Web/API/CLI/資料處理等）
當前存在的問題（目錄混亂、命名不一致、程式碼重複、註釋缺失等）
提出策略選擇（第一輪確認） - 向用戶展示：
專案概況摘要
四個策略級別及其包含的整理措施（見上方策略表）
推薦策略及理由
等待使用者確認或調整策略級別

Phase 1.5: 方案制定（第二輪確認）

基於使用者選擇的策略級別，生成詳細整理方案。

列出具體變更：
目錄結構調整詳情（如涉及）
每個需要修改的檔案及修改型別
預計可移除的無用程式碼/依賴
新增的檔案或配置
程式碼風格統一的具體規範
等待使用者明確確認後方可進入執行階段

Phase 2: 執行修改（並行子代理）

在收到明確批准後，按以下順序通過 sub-agents 並行執行

# 主會話根據使用者選擇的策略級別選擇任務
strategy = user_selected_strategy # "輕量清理" | "標準整理" | "深度重構" | "全面重構"
tasks = {
 # === 所有策略都適用 ===
 "code-cleanup": "清理無用程式碼和空目錄",
# === 標準整理及以上 ===
 "style-unify": "程式碼風格統一（格式/命名/import/型別/註釋）" if strategy in ["標準整理", "深度重構", "全面重構"] else None,
# === 深度重構及以上 ===
 "create-structure": "建立目錄結構/.gitignore" if strategy in ["深度重構", "全面重構"] else None,
 "move-files-phase1": "移動核心指令碼到對應目錄" if strategy in ["深度重構", "全面重構"] else None,
 "config-extract": "配置引數化" if strategy in ["深度重構", "全面重構"] else None,
 "add-tests": "補充單元測試" if strategy in ["深度重構", "全面重構"] else None,
# === 全面重構 ===
 "quality-check": "程式碼質量與設計規範檢查" if strategy == "全面重構" else None,
 "generate-docs": "生成三份文件" if strategy == "全面重構" else None,
}
tasks = {k: v for k, v in tasks.items() if v is not None} # 過濾掉不適用的任務
# 分批啟動子代理（避免 token 溢位）
batch_size = 3 # 每批最多 3 個子代理
for i in range(0, len(tasks), batch_size):
 batch = tasks[i:i+batch_size]
 for task_id, task_desc in batch.items():
 sessions_spawn(
 agentId="main", 
 label=task_id,
 task=f"""執行程式碼整理任務：{task_desc}
注意事項：
 1. 使用相對路徑操作檔案
 2. 每個子代理只負責自己的任務
 3. 完成後將結果寫入進度檔案 memory/organize-progress.json
 4. 如果任何步驟失敗，記錄錯誤並繼續其他步驟
輸出格式：
 {{\"status\": \"success|failed\", \"task\": \"{task_id}\", 
 \"files_modified\": [...], \"errors\": [...]}}""")

A. 目錄結構調整（子代理任務，深度重構及以上策略）

輕量/標準策略：保持現有結構，不做目錄重組 深度重構及以上：

project-root/
├── src/ # 原始碼
│ └── package_name/ # 主包
├── tests/ # 測試程式碼（可選）
├── configs/ # 配置檔案（可選，引數 >3 時建議）
├── scripts/ # 輔助指令碼、CLI 工具
├── docs/ # 專案文件（僅中型以上）
└── ...

根據專案型別可調整：

Web/API 應用 - src/app/routes.py, src/app/services/
資料處理專案 - src/pipeline/, data/, notebooks/
深度學習專案 - models/, trainers/, experiments/

B. 程式碼風格統一（子代理任務，標準整理及以上策略）

輕量清理策略跳過此步驟 - 標準整理及以上策略執行以下全部規則：

B1. 程式碼格式規範

行長限制：單行不超過 88 字元（Black 預設）或 120 字元（Ruff 推薦）
縮排：空格（Python PEP 8 標準），禁止混用 Tab 和空格
空行：頂層定義之間 2 空行，類方法之間 1 空行，函式內邏輯塊之間可 1 空行
行尾：不保留多餘空白字元，檔案末尾保留一個換行符
引號：統一使用雙引號 "（字串內容含雙引號時使用單引號 '）
運算子周圍：二元運算子兩側各一個空格（a + b），一元運算子緊貼運算元（-x）
逗號後：跟一個空格（[1, 2, 3]）
工具推薦：使用 Black 或 Ruff format 自動格式化

B2. 命名規範

模組/包名：snake_case，簡短描述性（data_loader.py，user_service/）
類名：PascalCase（DataLoader，UserService）
函式/方法：snake_case，動詞開頭（fetch_user()，validate_input()）
變數：snake_case，語義化命名（user_list 而非 ul，parsed_records 而非 data）
常量：UPPER_SNAKE_CASE（MAX_RETRIES = 3，API_BASE_URL）
私有成員：前導下劃線（_internal_cache，__private_method）
布林變數：is_/has_/can_/should_ 字首（is_valid，has_permission）
避免：單字母變數（除 i/j/k 迴圈索引和數學公式外）、縮寫（usr 為 user）

B3. Import 排序

遵循三段式分組 + 組內字母序：

# 1. 標準庫
import os
import sys
from pathlib import Path

# 2. 第三方庫
import numpy as np
import requests
from flask import Flask

# 3. 本地模組
from .config import Settings
from .models.user import UserModel
from utils.helpers import format_date

優先使用絕對匯入，避免相對匯入（模組移動時不會自動更新）
每組之間空一行
組內按字母順序排列
從每個模組做具體匯入（from .models.user import UserModel），而非 import models.user
工具推薦：使用 Ruff（I 規則）或 isort 自動排序

B4. 型別標註

函式簽名：所有公共函式必須標註引數型別和返回型別

def fetch_user(user_id: int, include_deleted: bool = False) -> User | None:
 ...

類屬性：在 __init__ 或類體中宣告型別

class DataProcessor:
 batch_size: int = 32
 shuffle: bool = True

集合型別：使用具體泛型（list[str] 而非 list，dict[str, int] 而非 dict）
可選型別：使用 X | None（Python 3.10+）或 Optional[X]
聯合型別：使用 A | B（Python 3.10+）或 Union[A, B]
複雜返回：使用 typing.TypeAlias 定義類型別名
不強求：內部工具函式、一次性指令碼、lambda 表示式可省略

B5. 規範註釋

註釋哲學：註釋是"必要的惡"。優先選擇重新命名而非寫註釋

必須添加註釋的情況：

解釋意圖（why），而非描述做了什麼（what）
✅ "使用 Adam 最佳化器因為收斂更快"
❌ "遍歷列表"（程式碼已自解釋）
法律條款/許可宣告
警告副作用（併發注意事項、全域性狀態修改、網路 I/O）
不透明的第三方庫行為解釋
臨時方案標記（# TODO:, # HACK:, # FIXME:）

Docstring 規範（公共函式/類必須）：

def process_data(records: list[Record], batch_size: int = 32) -> list[Batch]:
 """將記錄列表分批處理
對輸入記錄進行過濾、轉換和分批，返回處理後的批次列表
Args:
 records: 原始記錄列表
 batch_size: 每個批次的記錄數，預設 32
Returns:
 處理後的批次列表，每個批次包含最多 batch_size 條記錄
Raises:
 ValueError: 當 records 為空或 batch_size 小於 1 時
"""

類 Docstring：

class DataProcessor:
 """高效處理並分批輸入記錄
處理記錄的過濾、轉換和分批操作，設計為可子類化
以支援自定義處理管道
Attributes:
 batch_size: 每批次記錄數（預設 32）
 shuffle: 每個 epoch 是否打亂資料集
 num_workers: 資料載入的並行工作執行緒數
Example:
 >>> processor = DataProcessor(batch_size=64, shuffle=True)
 >>> for batch in processor:
 ... print(len(batch))
"""

行內註釋規範：

放在程式碼上方（非右側），複雜邏輯前留空行
以大寫開頭，句號結尾，完整句子
與程式碼保持相同縮排級別
小蔥技能站7w4.net每天更新，海量AI技能等你發現。
# 後跟一個空格

禁止：

冗餘註釋（遞增 i："i += 1"）
過時的註釋（程式碼已改但註釋未更新）
註釋掉的程式碼塊（應 git 歷史追蹤，不用註釋保留）

C. 程式碼清理

移除未使用的 import 和變數
合併重複功能
標記過時的依賴

D. 冗餘程式碼清理（新增）

深入分析並最佳化：

Dead Code Detection - 檢測死程式碼
從未呼叫的函式/類
條件分支中永遠不會執行的程式碼路徑
被註釋掉的遺留程式碼塊
殘餘目錄清理 - 刪除重構後留下的空目錄和舊檔案：
識別並刪除空目錄：原演算法目錄（重構遷移後遺留的空子目錄應在清理階段移除）
移動或移除原始輸入資料：如測試樣本、演示檔案等，根據專案原則放入 data/ 目錄或刪除
清理 .idea/, __pycache__/：確保所有 IDE 快取、Python 位元組碼被排除在版本控制外
確認無重複檔案：避免新舊程式碼在同一目錄下共存
Duplicate Logic Removal - 消除重複邏輯
識別相似功能模組（如多個檔案中的日誌初始化）
提取為公共工具函式放入 utils/
Legacy Code Marking - 標記過時依賴
Python 2 相容程式碼
已廢棄的 API 呼叫
過時的第三方庫版本

E. 配置引數化（深度重構及以上策略）

輕量/標準策略：不執行配置引數化。如果硬編碼值不超過 3 個，保持 inline 即可
深度重構及以上策略或引數 >3 時：執行以下操作：
Magic Number Extraction - 魔法數字提取

# 改進前（引數超過 2-3 個）
api_client = create_client(host="api.example.com", port=8080, timeout=30)

# 改進後 - 通過配置檔案
config = load_config("configs/default.yaml")
api_client = create_client(config.api.host, config.api.port, config.api.timeout_seconds)

YAML Configuration Structure - 標準配置格式
Command Line Override - 命令列引數優先（僅適用於 CLI/工具指令碼）

F. 單元測試補充（深度重構及以上策略）

輕量/標準策略：不強制編寫單元測試。原型程式碼、一次性實驗指令碼不需要測試覆蓋。如果確實有核心邏輯需要驗證，只寫最簡單的 assert 檢查即可
深度重構及以上策略：為核心邏輯新增測試用例
Critical Path Coverage - 關鍵路徑測試
I/O 操作（檔案讀寫、網路請求）
核心業務邏輯/演算法處理
資料驗證與轉換流程
Test Structure - 推薦測試結構
Test Framework Selection - 推薦框架（pytest 優先）
Minimum Test Coverage - 最低覆蓋率要求 - 0%

Phase 3: 進度持久化與驗證

每個子代理完成後必須寫入進度檔案

// memory/organize-progress.json (由主會話建立和維護)
{
 "project": "E:\\LPR",
 "started_at": "2026-04-28T00:00:00+08:00",
 "phases": {
 "create-structure": {"status": "completed", "files_created": [".gitignore"]},
 "move-files-phase1": {"status": "in_progress"},
 ...
 },
 "resumable": true,
 "last_checkpoint": "2026-04-28T00:05:00+08:00"
}

主會話在啟動時檢查進度：

如果存在 memory/organize-progress.json 且包含未完成階段 - 跳過已完成階段，繼續執行剩餘任務
如果檔案不存在或專案未開始 - 從頭開始

Phase 3.5: 程式碼質量與設計規範檢查（全面重構策略）

核心原則：僅在使用者選擇全面重構策略時執行深度程式碼質量檢查

A. 函式設計規範

長度 - 理想 4-10 行，不超過兩三層縮排；超過則拆分子函式
引數數量 - 1-2 個最佳，>5 應使用配置物件/資料類封裝
布林引數是程式碼氣味 - 一個布林引數暗示函式做了兩件不同的事，應拆分為兩個獨立函式（DoS 原則）
命令 - 查詢分離 (CQS) - 函式要麼執行動作（Command），要麼返回資訊（Query），不能兩者兼顧

B. OOP SOLID 六大原則

對每個類用以下自檢問題檢驗：

SRP (Single Responsibility) - 能否用 25 字以內描述其職責而不含 "if/and/or/but"？
OCP (Open-Closed) - 能否擴充套件行為而無需修改原始碼（開閉原則）？
LSP (Liskov Substitution) - 子類物件能否替換父類物件而不改變程式正確性？
ISP (Interface Segregation) - 介面是否足夠小，消費者不依賴他們不使用的方法？
DIP (Dependency Inversion) - 高層模組是否依賴抽象而非具體實現？

C. 錯誤處理規範

異常優先於返回碼 - 使用 try/except 替代檢查特殊返回值
禁止返回或傳遞 None 表示"無" - Python 中應返回空列表 []、空字典 {} 等；僅在語義上確實可能缺失時才用 Optional[Type]
封裝第三方 API - 將外部庫呼叫包裝在內部介面後，使程式碼可測試和 mock

D. 註釋哲學

註釋是"必要的惡"。優先選擇重新命名而非寫註釋。僅以下情況應添加註釋：

解釋意圖（why），而非描述做了什麼（what） - ✅ "使用 Adam 最佳化器因為收斂快"；❌ "遍歷列表"
法律條款 / 許可宣告
警告可能的後果（如副作用、併發注意事項）
對第三方/外部庫行為的不透明之處做解釋

E. Google-style Docstring 模板

公共函式/方法必須新增，遵循以下格式：

def fetch_user(user_id: int, include_deleted: bool = False) -> User | None:
 """Fetch a user by ID with optional deleted flag."""
 ...

class DataProcessor:
 """Efficiently processes and batches input records.
This class handles filtering, transformation, and batching of data.
It is designed to be subclassed for custom processing pipelines.
Attributes:
 batch_size: Number of records per batch (default: 32).
 shuffle: Whether to shuffle the dataset every epoch.
 num_workers: Number of parallel workers for data loading.
Example:
 >>> processor = DataProcessor(batch_size=64, shuffle=True)
 >>> for batch in processor:
 ... print(len(batch))
"""

F. 匯入組織規則（Import Organization）

優先使用絕對匯入 - 避免相對匯入，因為模組移動時不會自動更新
標準庫 - 第三方庫 - 原生代碼（三段式 + 空行分隔）
每組內部按字母順序排列
從每個 import 組內做具體匯入（如 from .models.resnet import ResNet50），而非 import models.resnet

文件生成規範

所有 4 級策略均生成三份文件（README.md、MODIFICATIONS.md、NOTE.md），區別在於詳盡程度

策略級別	README.md	CHANGELOG.md	NOTE.md
輕量清理	1-2 句話的專案說明	僅列出修改的檔案	1-2 句話的專案用途
標準整理	標準模板（Features + Quick Start）	列出修改類別和關鍵變更	標準模板（用途 + 快速開始 + 技術棧）
深度重構	完整模板（Features + 結構 + 配置 + 許可證）	詳細變更記錄 + 驗證清單	完整模板（含常用配置表）
全面重構	完整模板 + 架構圖/流程圖	詳細記錄 + 常見問題排查 + 驗證清單	完整模板 + 注意事項

README.md - 使用者面向文件

輕量清理 - 1-2 句話說明專案用途即可
標準整理 - 標準模板，包含 Features + Quick Start
深度重構 - 完整模板，包含 Features、Project Structure、Quick Start、Configuration、License
全面重構 - 完整模板，可額外包含架構圖或流程圖

# [專案名稱]
[簡短的專案描述 - 一句話概括專案目的]
## Features
- [功能 1]
- [功能 2]
- ...
## Project Structure
[新的目錄結構樹]
## Quick Start
```bash
pip install -r requirements.txt
python main.py --config configs/default.yaml

Configuration

[配置檔案說明]

License

[許可證資訊，如已知]

**要求**：簡潔明瞭，面向終端使用者或使用者

---
### CHANGELOG.md - 修改記錄
- **輕量清理** - 僅列出修改的檔案
- **標準整理** - 列出修改類別和關鍵變更
- **深度重構** - 詳細變更記錄 + 驗證清單
- **全面重構** - 詳細記錄 + 常見問題排查 + 驗證清單
```markdown
# Modifications Log
## Directory Restructuring
- Moved `model.py` to `models/definition.py`
- Created `utils/helpers.py` from scattered functions
- ...
## Code Style Changes
- Renamed variable `raw_data` to `parsed_records` (semantic naming)
- Added type annotations to [N] functions
- Reorganized imports in [N] files
- ...
## Cleanup
- Removed unused import: `os.path.join` (replaced by `pathlib`)
- Consolidated duplicate validation logic into `utils/validators.py`
- ...
## Comment Updates
- Added docstrings to [N] functions
- Standardized comment format across all files

## Troubleshooting Notes（常見問題排查）
### 問題 1: [錯誤描述]
**原因**: [根本原因分析]
**解決**: [解決方案步驟]

---
驗證清單：
- [x] 所有 import 路徑已更新
- [x] 型別提示已新增

要求：具體、可追溯，列出實際變更項。輕量策略可簡化為檔案列表

NOTE.md - 個人筆記（中文）

輕量清理 - 1-2 句話說明專案用途
標準整理 - 標準模板（用途 + 快速開始 + 技術棧）
深度重構 - 完整模板（含常用配置表）
全面重構 - 完整模板 + 注意事項

# [專案名稱] 筆記
## 專案用途
[用一兩句中文概括這個專案是做什麼的、解決什麼問題]
## 快速開始
```bash
# 安裝依賴
pip install -r requirements.txt
# 基本使用示例
python main.py [options]

常用配置（按需調整）

配置項	說明
[配置 A]	[預設值/建議範圍] - [簡要用途]
[配置 B]	[預設值/建議範圍] - [簡要用途]

技術棧

[技術棧描述，如 Python + Flask / Node.js / etc.]

**要求**：保持精簡（不超過一頁），中文撰寫，只包含核心使用資訊。不要包含**修改記錄、常見問題排查、程式碼改進說明等內容**

---
### ⚠️ 三檔案不重疊原則
| 檔案 | 側重 |
|------|--------|
| README.md | **是什麼 + 怎麼用** - 面向外部使用者 |
| CHANGELOG.md | **改了什麼** - 變更歷史記錄 |
| NOTE.md | **專案概況** - 個人快速參考 |

避免內容重複：README 不記錄修改細節，MODIFICATIONS 不解釋功能用途，NOTE 不做詳細技術文件

---
## 安全注意事項
1. **始終先分析再行動** - 不要擅自修改任何檔案
2. **保留原始備份意識** - 如果使用者要求，可建議建立 git 快照
3. **不做破壞性操作** - 不刪除未確認的檔案或程式碼
4. **尊重專案現有結構** - 除非有明顯改進空間

---
## PyTorch / 深度學習專案特殊處理
針對深度學習專案的額外考慮（如適用）：
- **模型檔案**：`models/` 目錄下按架構分類（如 `models/resnet.py`, `models/custom_net.py`）
- **資料**：`data/` 或 `datasets/`，區分預處理和原始資料路徑
- **實驗管理**：建立 `experiments/` 目錄存放訓練指令碼、checkpoint、日誌
- **配置優先**：將超引數（batch_size, lr, epochs 等）提取到 `configs/` YAML 檔案
- **日誌輸出**：確保有統一的 logging 機制（建議用 Python stdlib `logging` 或 `loguru`）

## Web / API 應用特殊處理
針對 Web/API 專案的額外考慮：
- **路由組織** - FastAPI/Flask 按資源劃分路由（`routes/users.py`, `routes/orders.py`）
- **中介軟體與鑑權** - 認證邏輯獨立為 middleware 或 service
- **資料庫遷移** - Alembic 或類似工具管理 schema 變更

## CLI / 資料處理專案特殊處理
針對命令列工具和 ETL 管道的額外考慮：
- **配置集中** - 配置檔案 + argparse / Typer，確保引數可追溯
- **日誌與進度** - rich / click 的進度條支援，便於長時執行的管道監控

---
## Python 專案結構規範（補充）
### A. __init__.py 作為公共 API 邊界（深度重構及以上策略）
- **輕量/標準策略 / Flat Layout** - 通常不需要 `__init__.py`，也不需要 `__all__`
- **深度重構及以上且使用 src layout** - 
 - `__init__.py` 不應包含業務邏輯，僅用於重新匯出子模組的公開介面
 - 使用 `__all__` **顯式宣告**公共 API - 不在列表中的 symbol 視為私有
 ```python
 # __init__.py
 from .user_service import UserService
 from .auth import AuthProvider

 __all__ = ["UserService", "AuthProvider"]

消費者應 import package 然後使用公開符號，而非直接 import package.inner_module

B. src/ vs Flat Layout - 決策框架

特徵	src/ layout（推薦）	Flat layout
適用場景	庫、可釋出專案、測試需要模擬包匯入	簡單指令碼、一次性分發/Notebook
優點	防止誤用未安裝包執行；`pip install -e .` 行為一致	結構簡單，路徑簡單
缺點	多一層目錄巢狀	開發時可能無意中匯入本地模組而非安裝的包

深度重構及以上策略 - 建議使用 src/ layout：src/package_name/ + tests/
輕量/標準策略 / Flat Layout - 保持扁平結構即可（如 main.py, utils.py, config.yaml）
現有 flat 專案無需強制遷移，除非有明確的包隔離需求

C. Layered Architecture - 分層架構（全面重構策略）

輕量/標準/深度重構策略 - 不要強行拆分多層。保持現有結構或輕度重組即可
全面重構策略且涉及多模組互動時，按技術棧分層（從高層到低層），依賴只能單向向下：

api/ # FastAPI/Flask 路由、請求/響應模型
services/ # 業務邏輯入口點，呼叫 repositories
repositories/ # 資料訪問層，與資料庫/外部 API 互動
models/ # Pydantic 模型 / SQLAlchemy ORM
schemas/ # DTOs, input validation schemas
config/ # 配置載入、環境管理

每層只能 import 下層模組，禁止跨層或反向匯入
通過依賴注入（建構函式引數）而非全域性例項來耦合層間關係

D. Domain-Driven Organization（DDD 風格，全面重構策略）

當專案複雜度較高且使用者選擇全面重構策略時，按業務域劃分而非技術層：

users/ # 使用者域
├── models.py # 領域模型
├── services.py # 領域服務
└── api.py # API 端點
orders/ # 訂單域
...
shared/ # 跨域的公共基礎設施（日誌、快取等）

DDD 結構適用於團隊多人協作的大型專案
輕量/標準/深度重構策略仍推薦傳統的 layered architecture，避免過度工程化

E. 模組粒度 - "一個概念一個檔案"（深度重構及以上策略）

拆分閾值：單個檔案超過 300-500 行或處理多個不相關職責時應拆分為獨立檔案
檔案命名：snake_case、描述性強（如 user_repository.py，而非 repo.py）
類名與檔名匹配：UserService 應放入 user_service.py

F. 測試組織 - Co-located vs Parallel（深度重構及以上策略）

輕量/標準策略 - 不寫單元測試
深度重構及以上策略

- 兩種策略任選其一併在整個專案中保持一致：

策略	結構	適用場景
Co-located（推薦）	`tests/test_<module>.py` 與原始碼同目錄	小型專案、測試邏輯與實現緊密相關
Parallel directory	`tests/` 映象 `src/` 目錄結構	大型專案、CI 需要獨立執行所有測試

G. pyproject.toml - 工具鏈配置（全面重構策略，或釋出為庫時）

輕量/標準/深度重構策略 - 不需要。指令碼直接執行即可
全面重構策略 / 需要釋出到 PyPI 的專案：在根目錄建立 pyproject.toml

[tool.ruff]
line-length = 120
target-version = "py311"

[tool.ruff.lint]
select = ["E", "W", "F", "I", "B", "UP", "SIM"]
# E/W: pycodestyle, F: Pyflask, I: isort, B: bugbear, UP: pyupgrade, SIM: simplify

[tool.ruff.lint.per-file-ignores]
"tests/**/*" = ["S101"] # allow assert in tests
"__init__.py" = ["F401"] # unused imports are re-exports by convention

[tool.mypy]
python_version = "3.11"
warn_return_any = true
warn_unused_configs = true
disallow_untyped_defs = false # production code: true; tests: override to false

⚠️ 避免過度工程化 - 具體禁令

以下行為不應預設執行，僅在使用者明確選擇對應策略級別或明確提出需求時才執行：

不要為只有幾個變數的指令碼建立 YAML/TOML 配置檔案 + argparse CLI - inline 引數更簡單（除非使用者選擇深度重構及以上策略）
不要將簡單的函式拆分成多個子函式以符合 4-10 行規則 - 保持邏輯完整性優先於行數限制（除非使用者選擇全面重構策略）
不要在扁平佈局的專案中強制建立 __init__.py + __all__ - 除非使用者選擇深度重構及以上策略
不要對只有一個類的檔案做 SRP/OCP/LSP/ISP/DIP 分析 - OOP 原則只在存在繼承和多型關係時才適用（除非使用者選擇全面重構策略）
不要為只有幾個檔案的深度學習/資料處理專案建立完整的分層架構或 DDD 結構 - 除非使用者選擇全面重構策略
不要在原型程式碼中強制要求單元測試和覆蓋率閾值 - 除非使用者選擇深度重構及以上策略
不要對只有一兩個使用者的內部工具生成 README + MODIFICATIONS + NOTE 三份文件 - 除非使用者選擇對應策略級別
不要將 main.py 強行塞進 src/package_name/ 的目錄結構中 - src layout 只對庫或大型應用有意義（除非使用者選擇深度重構及以上策略）

核心原則：最佳化是為了讓人更容易理解和維護程式碼，不是為了達到最佳實踐。如果改動讓專案變得更復雜而不是更簡單，那就做過頭了。使用者的策略選擇是最終決定

🤖 AI 評測

這個技能質量不錯，採用了漸進式的整理策略，使用者可以根據專案規模選擇合適的處理深度，操作安全性也有保障。好處是完全由使用者掌控節奏，不會擅自做主；缺點是文件偏長，閱讀起來需要一些耐心。總體來說是一個考慮周全、實用性強的程式碼整理工具，適合需要整理或重構 Python 專案的開發者使用。

📊 多維度評分

適應性4.2

規範性4.4

有效性4.7

可靠性3.8

可信度5

📁 包含檔案 (1 個)

📄 SKILL.md 30.9 KB