Dev Tools
📖 技能介紹
name: dev-tools description: 開發工具箱，提供規範管理、預提交檢查、錯誤診斷、技術債務跟蹤、程式碼差異對比、重構建議、依賴分析等開發輔助功能。
/dev-tools - 開發工具箱技能
技能 ID: dev-tools
技能名稱: 開發工具箱
版本: 2.0.0
描述: 提供開發過程中的輔助工具，包括規範管理、預提交檢查、錯誤診斷、技術債務跟蹤、程式碼差異對比、重構建議、依賴分析
觸發條件
/dev-tools/dev-tools spec/dev-tools pre-commit/dev-tools diagnose/dev-tools debt/dev-tools diff/dev-tools refactor/dev-tools dep規範管理、預提交檢查、錯誤診斷、技術債務程式碼差異、重構建議、依賴分析
技能邊界（防止誤觸發）
- 本技能僅當使用者要「使用開發輔助工具」時觸發
- 不得在以下場景觸發本技能：
- 使用者要「程式碼審查」→ 應使用 review-code
- 使用者要「驗證設計」→ 應使用 validate
- 使用者要「分析程式碼庫」→ 應使用 analyze
檔案落盤（P0）
小蔥技能站7w4.net發現了升級外掛。
凡子命令向倉庫寫入報告或匯出檔案（Markdown、JSON、HTML 等）時，須遵守 SKILLS-FILE-OUTPUT.md：寫入前確保目標父目錄已存在。本子技能常見目錄包括 docs/tech-debt/、docs/diff/、docs/refactor/、docs/analysis/（依子命令與引數而定）；自定義 --output 時同樣須先建立父目錄。
子命令
1. spec - 規範管理
功能：管理專案規範，包括規範版本管理、專案規範定製、規範衝突檢測
用法：
/dev-tools spec # 檢視規範管理選單
/dev-tools spec view # 檢視當前規範
/dev-tools spec customize # 定製專案規範
/dev-tools spec update # 更新規範版本
/dev-tools spec conflict # 檢測規範衝突
功能模組： - 規範版本管理：檢視規範版本、檢查更新、更新規範 - 專案規範定製：定製命名規範、程式碼格式、註釋規範、技術棧規範 - 規範衝突檢測：檢測內嵌規範與專案規範的衝突並提供解決方案
輸出檔案：
.ads/project-specs/naming.md
.ads/project-specs/code-style.md
2. pre-commit - 預提交檢查
功能：程式碼提交前進行檢查，確保符合規範和質量標準
用法：
/dev-tools pre-commit # 檢查當前修改
/dev-tools pre-commit src/points/ # 檢查指定目錄
檢查專案：
P0 檢查（必須通過）： - 編譯通過 - 無嚴重安全問題 - 無嚴重空指標風險 - 測試通過率 100% - 無敏感資訊洩露
P1 檢查（推薦通過）： - 程式碼規範遵循 - 測試覆蓋率>80% - 無重複程式碼 - 註釋完整 - 提交資訊規範
示例輸出：
**預提交檢查**：
P0 檢查：
✅ 編譯通過
✅ 無嚴重安全問題
✅ 無嚴重空指標風險
✅ 測試通過率 100%
✅ 無敏感資訊洩露
P1 檢查：
✅ 程式碼規範遵循（95%）
⚠️ 測試覆蓋率 78%（目標 80%）
✅ 無重複程式碼
✅ 註釋完整
**檢查結果**：
- P0 檢查：5/5 通過 ✅
- P1 檢查：4/5 通過 ⚠️
**結論**：可以通過提交，但建議提升測試覆蓋率。
是否繼續提交？
A) 繼續提交 B) 修復後重新檢查 C) 取消提交
3. diagnose - 錯誤診斷
功能：診斷執行過程中的錯誤，分析原因並給出解決方案
用法：
/dev-tools diagnose # 診斷最近一次錯誤
/dev-tools diagnose --skill=gen-code --task=Task-001 # 診斷指定技能錯誤
診斷流程： 1. 收集錯誤資訊（技能名稱、錯誤描述、時間） 2. 分析可能原因（給出機率評估） 3. 執行診斷步驟（逐步排查） 4. 給出診斷結論 5. 提供解決方案（多個方案供選擇）
示例輸出：
**錯誤診斷**：
**錯誤資訊**：
- 技能：/gen-code Task-001
- 錯誤：程式碼生成失敗
- 時間：2026-03-01 10:30:00
**錯誤分析**：
可能原因：
1. 設計文件不存在（機率 60%）
2. 任務描述不清晰（機率 30%）
3. 規範衝突（機率 10%）
**診斷步驟**：
步驟 1/3：檢查設計文件
✅ 設計文件存在
步驟 2/3：檢查任務描述
❌ 任務描述不清晰
**診斷結論**：
錯誤原因：任務描述不清晰
**解決方案**：
方案 A（推薦）：
修改任務描述為具體內容
方案 B：
重新生成任務列表
是否需要我幫助修改任務描述？
A) 是 B) 否 C) 取消
4. debt - 技術債務跟蹤
功能：跟蹤和管理技術債務，定期生成技術債務報告
用法：
/dev-tools debt # 檢視技術債務選單
/dev-tools debt list # 列出技術債務清單
/dev-tools debt add # 新增技術債務
/dev-tools debt report # 生成債務報告
/dev-tools debt fix TD-001 # 標記債務為已修復
功能模組：
債務清單：
| 編號 | 描述 | 優先順序 | 狀態 |
|------|------|--------|------|
| TD-001 | 積分扣減未加事務 | P0 | 待修復 |
| TD-002 | 併發扣減可能超扣 | P0 | 待修復 |
| TD-003 | 積分規則硬編碼 | P2 | 待修復 |
**統計**：
- 總債務數：4
- P0 債務：2
- P1 債務：1
- P2 債務：1
新增債務：
**新增技術債務**：
描述：積分規則硬編碼，不支援動態配置
優先順序：P2
預計修復時間：2h
是否新增？
A) 新增 B) 修改 C) 取消
債務報告：
**技術債務報告**：
**債務趨勢**：
| 日期 | 新增 | 修復 | 累計 |
|------|------|------|------|
| 2026-03-01 | 4 | 0 | 4 |
**修復建議**：
1. 優先修復 P0 債務（2 個）
2. 本週修復 P1 債務（1 個）
**預計工時**：總計 8h
輸出檔案：
docs/tech-debt/YYYY-MM-DD-debt-report.md
5. diff - 程式碼差異對比
功能：對比新生成程式碼與現有程式碼的差異，生成視覺化報告
用法：
/dev-tools diff # 對比工作區變更
/dev-tools diff --original=src/ --generated=.gen/ # 對比指定目錄
/dev-tools diff --file=PointsService.java # 對比單個檔案
/dev-tools diff --staged # 對比暫存區變更
/dev-tools diff --commit=HEAD~1 # 對比最近一次提交
引數說明：
| 引數 | 型別 | 說明 |
|---|---|---|
--original |
string | 原始程式碼路徑，預設當前程式碼 |
--generated |
string | 生成的程式碼路徑 |
--file |
string | 指定對比的檔案 |
--staged |
flag | 對比暫存區變更 |
--commit |
string | 對比指定提交 |
--format |
enum | 輸出格式：markdown / html / json，預設 markdown |
--context |
number | 上下文行數，預設 3 |
輸出示例：
**程式碼差異對比報告**
## 概覽
- 新增檔案: 3
- 修改檔案: 5
- 刪除檔案: 1
- 新增行數: 234
- 刪除行數: 56
- 淨增行數: 178
## 檔案變更詳情
### 新增檔案
| 檔案 | 行數 | 說明 |
|------|------|------|
| PointsServiceV2.java | 156 | 新版積分服務 |
### 修改檔案
#### PointsController.java
```diff
- public Result earnPoints(Long userId, Integer points) {
+ public Result earnPoints(Long userId, Integer points, String source) {
// 新增來源引數，支援多渠道積分
影響分析
- 影響模組: points-service
- 影響介面: 3 個
- 風險等級: 中
是否檢視詳細差異？ A) 檢視全部 B) 按檔案檢視 C) 匯出報告
**輸出檔案**：
docs/diff/YYYY-MM-DD-diff-report.md
---
### 6. refactor - 重構建議生成
**功能**：基於程式碼庫分析結果，自動生成重構建議和重構方案
**用法**：
```bash
/dev-tools refactor # 生成重構建議
/dev-tools refactor --analysis=docs/analysis/codebase-analysis.md # 基於分析報告
/dev-tools refactor --scope=points-service # 指定模組
/dev-tools refactor --type=code-smell,architecture # 指定型別
/dev-tools refactor --priority=high # 僅高優先順序
/dev-tools refactor --apply=RF-001 # 應用指定重構建議
引數說明：
| 引數 | 型別 | 說明 |
|---|---|---|
--analysis |
string | 程式碼庫分析報告路徑 |
--scope |
string | 範圍：module / service / full |
--type |
array | 重構型別：code-smell / architecture / performance / security |
--priority |
enum | 優先順序：high / medium / low |
--apply |
string | 應用指定重構建議的 ID |
重構型別說明：
| 型別 | 觸發條件 | 重構動作 |
|---|---|---|
| code-smell | 重複程式碼、過長方法、過大類 | 提取方法、提取類 |
| architecture | 迴圈依賴、邊界違規 | 解耦、分層調整 |
| performance | N+1查詢、迴圈內IO | 批次查詢、快取最佳化 |
| security | SQL隱碼攻擊、敏感資訊洩露 | 引數化查詢、加密處理 |
輸出示例：
**重構建議報告**
## 重構概覽
- 總建議數: 12
- 高優先順序: 3
- 中優先順序: 5
- 低優先順序: 4
- 預計收益: 程式碼質量提升 25%
## 高優先順序重構建議
### RF-001: 解耦訂單與支付服務
- **問題**: 訂單服務直接呼叫支付服務內部實現
- **影響**: 違反服務邊界，增加耦合
- **建議**: 通過API閘道器呼叫，使用事件驅動解耦
- **預計工時**: 8h
- **風險等級**: 中
### RF-002: 提取積分計算邏輯
- **問題**: 積分計算邏輯散落在多個方法中
- **影響**: 程式碼重複，難以維護
- **建議**: 提取獨立的 PointsCalculator 類
- **預計工時**: 4h
- **風險等級**: 低
## 重構方案
### 方案一：漸進式重構（推薦）
1. 先處理高優先順序問題
2. 每次重構後執行測試
3. 分階段驗證
是否檢視詳細方案？
A) 檢視全部 B) 按優先順序檢視 C) 匯出報告 D) 應用建議
輸出檔案：
docs/refactor/YYYY-MM-DD-refactor-suggest.md
7. dep - 依賴分析與邊界檢查
功能：分析程式碼依賴關係，檢測迴圈依賴和服務邊界違規
用法：
/dev-tools dep # 完整依賴分析
/dev-tools dep --check-cycle # 僅檢查迴圈依賴
/dev-tools dep --check-boundary # 僅檢查邊界違規
/dev-tools dep --module=order-service # 分析指定模組
/dev-tools dep --format=mermaid # 輸出 Mermaid 圖譜
/dev-tools dep --design-line=docs/design/design-line.md # 基於設計主線檢查
引數說明：
| 引數 | 型別 | 說明 |
|---|---|---|
--check-cycle |
flag | 僅檢查迴圈依賴 |
--check-boundary |
flag | 僅檢查邊界違規 |
--module |
string | 分析指定模組 |
--format |
enum | 輸出格式：markdown / mermaid / json |
--design-line |
string | 設計主線文件路徑 |
分析維度：
| 維度 | 檢查項 | 問題級別 |
|---|---|---|
| 模組依賴 | 迴圈依賴、單向依賴 | 錯誤 |
| 服務邊界 | 跨服務資料庫訪問、內部實現呼叫 | 錯誤 |
| 包依賴 | 不合理依賴、反向依賴 | 警告 |
| 類依賴 | 高耦合、缺少介面 | 建議 |
輸出示例：
**依賴分析報告**
## 依賴概覽
- 總模組數: 8
- 總依賴數: 24
- 迴圈依賴: 2
- 邊界違規: 3
- 風險等級: 高
## 迴圈依賴
### CD-001: order-service ↔ payment-service
order-service → payment-service → order-service
**影響**: 編譯順序問題、執行時風險
**建議**: 引入中間層或事件驅動解耦
## 邊界違規
### BV-001: 訂單服務直接訪問支付資料庫
- **位置**: OrderServiceImpl.java:156
- **程式碼**: paymentMapper.selectByOrderId(orderId)
- **違規型別**: 跨服務資料庫訪問
- **修復建議**: 通過支付服務API獲取資料
## 依賴圖譜
```mermaid
graph TD
A[user-service] --> B[points-service]
A --> C[order-service]
C --> D[payment-service]
C --> E[notification-service]
是否檢視詳細分析？ A) 檢視全部 B) 僅看問題 C) 匯出圖譜 D) 生成修復方案
**輸出檔案**：
docs/analysis/dependencies.md docs/analysis/dependency-graph.md
---
## 與其他技能的關係
### 與 review-code 的區別
| 維度 | dev-tools pre-commit | review-code |
|------|---------------------|-------------|
| 目的 | 提交前快速檢查 | 詳細程式碼審查 |
| 輸出 | 通過/不通過判斷 | 問題清單 |
| 使用時機 | 程式碼提交前 | 程式碼完成後 |
| 檢查項 | P0/P1 關鍵檢查項 | 完整規範對照 |
### 典型使用場景
開發過程中
/dev-tools spec customize # 定製專案規範
開發完成
/dev-tools pre-commit # 提交前檢查
如果出錯
/dev-tools diagnose # 診斷錯誤
程式碼審查後
/dev-tools debt add # 記錄發現的技術債務
專案復盤
/dev-tools debt report # 生成債務報告
存量專案增強（新增）
/dev-tools diff # 程式碼差異對比 /dev-tools refactor # 生成重構建議 /dev-tools dep # 依賴分析與邊界檢查
### 存量專案推薦流程
1. 程式碼變更後對比
/gen-code Task-001 /dev-tools diff --staged # 對比生成的程式碼變更
2. 發現問題後分析
/dev-tools dep --check-boundary # 檢查邊界違規 /dev-tools refactor --priority=high # 生成高優先順序重構建議
3. 技術債務管理
/dev-tools debt list # 檢視債務清單 /dev-tools debt report # 生成債務報告
4. 提交前檢查
/dev-tools pre-commit # 最終檢查 ```
相關技能
- review-code / gen-test：審查與測試之後的預提交（
pre-commit）與債務（debt）記錄。 - analyze：diff / refactor / dep 常與分析報告、依賴圖譜配合。
- gen-code：生成程式碼後用 diff 做變更視覺化。
- spec 子命令：與
docs/coding-specs/文件規範互補——前者偏工具與後設資料，團隊編碼約定以coding.*.md為準。
全鏈路見 SKILL-VALUE-CHAIN.md。
版本歷史
| 版本 | 日期 | 變更說明 |
|---|---|---|
| 2.0.0 | 2026-03-07 | 新增程式碼差異對比（diff）、重構建議生成（refactor）、依賴分析與邊界檢查（dep） |
| 1.0.0 | 2026-03-01 | 初始版本 |
本技能是 AI Speckits 技能體系的開發工具集合。
🤖 AI 評測
這個開發工具箱質量還不錯，提供了一整套實用的開發輔助功能。規範管理和預提交檢查做得比較完善，能幫助開發者提升程式碼質量；錯誤診斷和技術債務跟蹤功能也很貼心。不過部分功能介紹得不夠詳細，缺少具體的使用示例；另外文件中有些地方的版本號對不上，看起來像是合併後沒有完全同步。總體來說，這是一個值得一試的工具，但使用前最好先仔細閱讀說明。
