DAA 程式碼審查技能
分析 Python 程式碼、Markdown 文件與 Mermaid 圖表,找出品質問題。結合外部 lint 工具 (ruff) 與 Claude 的分析,提供全面的程式碼審查與建議修正。 不僅是執行 ruff 與其他 lint 工具,而是檢查程式碼是否符合良好的軟體工程實踐 (SOLID、DRY、YAGNI、簡潔而非複雜)、安全性漏洞,以及具描述性的變數命名,例如:
請避免這樣做:
pkb = p_key.private_bytes(
encoding=serialization.Encoding.DER,
format=serialization.PrivateFormat.PKCS8,
encryption_algorithm=serialization.NoEncryption(),
)
請改這樣做:
private_key_bytes = p_key.private_bytes(
encoding=serialization.Encoding.DER,
format=serialization.PrivateFormat.PKCS8,
encryption_algorithm=serialization.NoEncryption(),
)
快速入門
分析 Python 程式碼
from python_analyzer import analyze_python, analyze_python_file
from report_generator import generate_console_report, generate_markdown_report
from models import ReviewReport
# 分析程式碼片段
result = analyze_python(code_string)
# 分析檔案
result = analyze_python_file(Path("src/module.py"))
# 產生報告
report = ReviewReport(results=[result], title="Code Review")
generate_console_report(report) # 主控台輸出
markdown = generate_markdown_report(report) # Markdown 字串
分析 Markdown
from markdown_analyzer import analyze_markdown, analyze_markdown_file
result = analyze_markdown(content)
# 或
result = analyze_markdown_file(Path("README.md"))
分析 Mermaid 圖表
對於 Mermaid 驗證,請使用 Claude 的理解能力,並結合網路搜尋最新語法。請參閱 mermaid-checks.md。
工作流程
- 接收程式碼 - 來自檔案路徑或貼上的片段
- 偵測檔案類型 - Python (.py)、Markdown (.md) 或 Mermaid (.mmd, 程式碼區塊)
- 執行分析 - 先執行外部 lint 工具,再進行 Claude 分析
- 產生報告 - 主控台與 Markdown 兩種格式
- 儲存報告 - 將 Markdown 報告寫入
docs/code_reviews/{YYYY-MM-DD}_{file_name}.md(必要時建立目錄) - 審查修正 - 向使用者呈現建議的修正
- 套用修正 - 經使用者核准 (彈性核准模式)
- 檢查 README - 在推送前,驗證 README.md 是否反映當前變更 (新功能、修改的 API、更新的依賴項、變更的設定)
分析能力
Python (透過 ruff + Claude)
| 類別 | 範例 | 嚴重性 |
|---|---|---|
| PEP8 | 行長度、縮排、空白 | WARNING/INFO |
| 未使用的程式碼 | 未使用的匯入、變數、引數 | WARNING |
| 型別提示 | 函式缺少型別註解 | INFO |
| Docstring | 缺少或格式錯誤的 numpy 風格 docstring | INFO |
| 複雜度 | 循環複雜度過高的函式 | INFO |
| 執行時期錯誤 | 未定義的名稱、語法錯誤 | ERROR |
| 匯入 | 未排序的匯入、禁止的匯入 | INFO |
Markdown
| 檢查項目 | 描述 | 嚴重性 |
|---|---|---|
| 標題結構 | 正確的 h1→h2→h3 順序 | WARNING |
| 損壞的連結 | 不存在的檔案連結 | ERROR |
| 缺少替代文字 | 缺少無障礙存取文字的圖片 | WARNING |
| 格式化 | 結尾空白、空白行 | INFO |
| 程式碼區塊 | 缺少語言識別碼 | INFO |
| 編碼損毀 | 出現 ×、âœ" 等 UTF-8 字元 | ERROR |
Mermaid
在驗證前,請先搜尋網路以取得最新的 Mermaid.js 文件。檢查項目:
- 圖表類型宣告
- 節點/邊的語法
- 結構正確性
- 關係定義
輸出格式
主控台 (互動式)
彩色輸出,附帶嚴重性指示:
- ✗ ERROR (紅色) - 必須修正
- ⚠ WARNING (黃色) - 應該修正
- ℹ INFO (藍色) - 考慮修正
Markdown 報告
儲存至 docs/code_reviews/{YYYY-MM-DD}_{file_name}.md。針對多檔案審查,請使用具描述性的名稱 (例如,2026-03-02_full_repo_review.md)。
結構化報告包含:
- 摘要統計
- 狀態徽章 (通過/失敗)
- 每個檔案的問題表格
- 可展開的問題詳細資訊
- 依類別劃分的統計
修正套用
修正可透過以下方式核准:
- 全部套用 - 套用所有可自動修正的問題
- 依類別 - 套用所有 PEP8 修正,跳過 docstring
- 依嚴重性 - 先修正錯誤,再修正警告
- 依檔案 - 僅修正特定檔案
- 逐一審查 - 逐一檢視每個修正
請參閱 fix-workflow.md 以了解詳細的工作流程。
參考文件
- python-checks.md - Python 規則詳細資訊
- markdown-checks.md - Markdown 規則詳細資訊
- mermaid-checks.md - Mermaid 驗證指南
- fix-workflow.md - 修正核准工作流程
使用範例
完整儲存庫審查
使用者:「請審查我專案中的程式碼品質」
1. 列出 Python 和 Markdown 檔案
2. 分析每個檔案
3. 匯整成 ReviewReport
4. 呈現主控台摘要
5. 將報告儲存至 docs/code_reviews/{YYYY-MM-DD}_full_repo_review.md
6. 提供套用修正的選項
快速程式碼檢查
使用者:[貼上程式碼片段]
「這段程式碼有問題嗎?」
1. 直接分析程式碼片段
2. 內嵌回報問題
3. 建議具體修正
提交前審查
使用者:「請在提交前檢查這些檔案」
1. 分析指定的檔案
2. 專注於錯誤與警告
3. 若發現錯誤則阻止提交
4. 若經核准則套用快速修正
5. 根據變更檢查 README 是否需要更新
6. 若新增功能、API 或依賴項有所變更,則更新 README
腳本
| 腳本 | 用途 |
|---|---|
models.py | 資料結構 (Issue, Severity, AnalysisResult) |
python_analyzer.py | 使用 ruff 進行 Python 分析 |
markdown_analyzer.py | Markdown 品質檢查 |
report_generator.py | 主控台與 Markdown 報告產生 |
需求
- Python 3.10+
- ruff (透過 pip 安裝)
- 查閱 Mermaid 文件所需的網路存取權限