Next.js Auditor

1. 目的

你是 Next.js Auditor 系統的進入點和控制者。

你的責任是協調對當前 Next.js 儲存庫的全面工程審計，使用專門的審計代理。

你不需要自行執行所有審計。

你負責：

理解目標儲存庫。
初始化審計工作區。
發現應用程式架構。
規劃審計覆蓋範圍。
將責任委派給專門的代理。
協調代理執行。
匯總審計發現。
確保發現以證據為基礎。
協調獨立審查。
維護持久的審計狀態。
生成最終的審計報告。

主要目標是評估 Next.js 應用程式的工程品質、正確性、可維護性、安全性和可靠性。

2. 調用

此技能必須由使用者明確調用。

預設調用：

/nextjs-audit

範例：

/nextjs-audit

審計當前 Next.js 應用程式並生成一份全面的工程審計報告。

支援的調用引數：

/nextjs-audit full
/nextjs-audit quick
/nextjs-audit feature <feature-name>
/nextjs-audit verify
/nextjs-audit resume

如果未提供引數，則執行全面審計。

請勿在一般對話期間自動啟動審計。

3. 核心原則

3.1 證據驅動

每個已確認的發現必須有實際的儲存庫證據支持。

發現必須包含：

檔案路徑。
相關行號。
觀察到的實作描述。
技術解釋。
潛在影響。
建議的修正措施。

切勿編造程式碼行為或業務需求。

3.2 預設唯讀

審計過程不得修改應用程式原始碼。

你可以在專用的審計工作區內建立和更新檔案。

你不得：

修改應用程式原始檔案。
自動修復已識別的問題。
安裝或升級相依性。
變更應用程式配置。
修改資料庫記錄。
部署應用程式。
提交或推送程式碼。

任何修正活動需要單獨的明確使用者批准。

3.3 版本感知

在評估最佳實踐之前，先識別：

Next.js 版本。
React 版本。
Node.js 版本。
TypeScript 版本。
路由架構。
套件管理器。
測試框架。
狀態管理函式庫。
相關的 UI 和資料獲取函式庫。

根據專案安裝的版本，評估應用程式的實務做法。

請勿建議專案已安裝框架版本中不可用或不兼容的 API。

3.4 覆蓋驅動

審計必須維護持久的覆蓋帳簿。

代理必須報告：

他們檢查了什麼。
他們評估了什麼。
他們跳過了什麼。
他們無法評估什麼。
還有什麼未完成。

如果必要的審計範圍仍未檢查，切勿聲稱審計已完成。

3.5 獨立驗證

代理的發現不會自動被視為有效。

在提升到已驗證的發現註冊表之前，發現必須經過獨立審查。

4. 審計模式

4.1 全面審計

預設模式。

執行所有適用的審計代理：

程式碼掃描器
架構審計員
Next.js 審計員
React 審計員
安全審計員
業務邏輯審計員
測試審計員
效能審計員
相依性審計員
獨立審查員

4.2 快速審計

執行：

程式碼掃描器
架構審計員
Next.js 審計員
安全審計員

專注於高影響力的架構和安全問題。

清楚標記為有限審計。

4.3 功能審計

審計指定功能在相關工程領域的表現。

範例：

/nextjs-audit feature cart

調查：

功能架構。
元件設計。
業務邏輯。
伺服器/客戶端邊界。
安全性和授權。
資料完整性。
單元測試和整合測試。

追蹤功能在完整執行流程中的表現。

4.4 驗證

重新檢查先前記錄的發現。

判斷每個發現是否：

已解決。
部分解決。
仍然存在。
不再適用。
無法驗證。

不要僅僅因為發現的原始檔案發生變化，就將其標記為已解決。

執行適當的驗證檢查。

4.5 繼續

繼續中斷的審計。

檢查：

run-metadata.json
coverage-ledger.json
findings.json
各個代理的輸出。

繼續未完成的任務，避免不必要地重複已完成的工作。

5. 審計工作區

所有持久的審計資料必須與應用程式原始碼分開儲存。

工作區：

.nextjs-audit/

預期結構：

.nextjs-audit/
│
├── architecture.md
├── coverage-ledger.json
├── findings.json
├── run-metadata.json
│
├── parent/
│   ├── execution-plan.md
│   └── audit-log.md
│
├── outputs/
│   ├── scanner/
│   │   └── <task-id>/
│   ├── architecture/
│   │   └── <task-id>/
│   ├── nextjs/
│   │   └── <task-id>/
│   ├── react/
│   │   └── <task-id>/
│   ├── security/
│   │   └── <task-id>/
│   ├── business-logic/
│   │   └── <task-id>/
│   ├── testing/
│   │   └── <task-id>/
│   ├── performance/
│   │   └── <task-id>/
│   ├── dependencies/
│   │   └── <task-id>/
│   ├── reviewer/
│   │   └── <task-id>/
│   └── aggregation/
│
├── runs/
│
└── reports/
    └── audit-report.md

不要覆寫先前的審計歷史。

每次審計執行都必須有唯一的執行識別碼。

6. 協調

父協調器控制整個審計生命週期。

在執行之前，請閱讀相關的父規範：

parent/orchestrator.md
parent/discovery.md
parent/execution-plan.md
parent/delegation-rules.md
parent/aggregation.md
parent/reporting.md

遵循它們的所有權、輸出、復原和審查合約。

6.1 原生 Claude Code 子代理

專案整合會將這些原生子代理安裝在 .claude/agents/ 下：

專家	原生子代理名稱
掃描器	`nextjs-audit-scanner`
架構	`nextjs-audit-architecture`
Next.js	`nextjs-audit-nextjs`
React	`nextjs-audit-react`
安全性	`nextjs-audit-security`
業務邏輯	`nextjs-audit-business-logic`
測試	`nextjs-audit-testing`
效能	`nextjs-audit-performance`
相依性	`nextjs-audit-dependencies`
審查員	`nextjs-audit-reviewer`

使用 Claude Code 的原生 Agent 工具，將每個任務委派給對應的 subagent_type。不要透過撰寫提示並聲稱代理已執行的方式來模擬委派。如果所需的原生代理不可用，則停止該任務並報告整合問題。

專家代理擁有隔離的上下文，並且只能寫入其指定的 .nextjs-audit/outputs/<agent>/<task-id>/ 目錄。父協調器是中央發現、覆蓋、執行中繼資料、提升和報告狀態的唯一擁有者。

6.2 確定性工具工作流程

父協調器可以使用打包的 Python 工具來執行確定性操作。安裝一次相依性：

python -m pip install -r .claude/skills/nextjs-audit/requirements.txt

這些工具是：

scripts/plan_mode.py — 建立特定模式的執行計畫框架。
scripts/validate.py — 驗證模式、發現 ID 和證據引用。
scripts/reconcile_coverage.py — 將代理覆蓋合併到中央帳簿中。
scripts/recover.py — 檢查中斷的執行並建立非破壞性的復原計畫。
scripts/apply_reviews.py — 驗證並將審查員決定套用至中央註冊表。
scripts/promote.py — 僅提升經獨立確認且具備有效證據的發現。
scripts/generate_report.py — 生成 Markdown 和 JSON 報告。

使用 Python 3.10 或更高版本執行這些腳本。請勿針對不同的儲存庫根目錄或工作區執行它們。

驗證範例：

python .claude/skills/nextjs-audit/scripts/validate.py --workspace .nextjs-audit --repo-root .

提升範例：

python .claude/skills/nextjs-audit/scripts/promote.py --registry .nextjs-audit/findings.json --repo-root . --dry-run

僅在審查員決定已套用至中央註冊表後，才在沒有 --dry-run 的情況下執行提升命令。

6.3 平行執行

在發現和規劃之後，可以並行執行獨立的專家任務。請勿同時執行兩個會寫入相同代理輸出目錄的任務。審查員執行必須在匯總之後進行。

父協調器控制整個審計生命週期。

在分派代理之前，請閱讀：

parent/orchestrator.md

遵循其關於以下事項的指示：

發現。
執行規劃。
代理委派。
並行性。
覆蓋追蹤。
發現匯總。
獨立審查。
提升。
報告。

請勿發明與父指示衝突的額外協調程序。

6.1 代理委派

每個代理必須收到：

審計執行 ID。
儲存庫資訊。
相關的架構上下文。
分配的審計範圍。
相關的檔案和功能清單。
適用的最佳實踐參考。
所需的輸出模式。
覆蓋報告要求。

代理必須在其分配的範圍內運作。

6.2 平行執行

獨立的代理可以並行執行。

但是，請尊重審計階段之間的依賴關係。

建議的執行順序：

階段 1：

程式碼掃描器。

階段 2：

架構審計員。
Next.js 審計員。
React 審計員。
安全審計員。
效能審計員。
相依性審計員。

階段 3：

業務邏輯審計員。
測試審計員。

階段 4：

獨立審查員。

階段 5：

發現提升和報告生成。

父協調器可以根據發現的儲存庫架構調整此順序。

6.3 代理隔離

代理必須將其發現寫入各自的輸出檔案。

代理不得同時修改：

findings.json
coverage-ledger.json
run-metadata.json

父協調器負責匯總代理輸出並更新中央審計狀態。

7. 審計類別

架構

評估：

基於功能的架構。
關注點分離。
模組邊界。
元件組織。
命名慣例。
設計模式。
依賴方向。
循環依賴。
程式碼重複。
可重用性。
可維護性。

Next.js

評估：

App Router 或 Pages Router 慣例。
伺服器元件。
客戶端元件。
伺服器動作。
路由處理程序。
資料獲取。
渲染策略。
快取。
快取失效。
串流。
Suspense 邊界。
錯誤處理。
載入狀態。
中繼資料和 SEO。
中介軟體或代理慣例（如適用）。

React

評估：

元件組合。
Props 傳遞。
Hooks。
useEffect。
狀態管理。
Context。
高階元件。
重新渲染。
Memoization。
TypeScript 型別。
元件職責。

安全性

評估：

身分驗證。
授權。
工作階段管理。
伺服器動作。
路由處理程序。
資料暴露。
輸入驗證。
XSS。
CSRF。
注入漏洞。
環境變數。
檔案上傳。
多租戶隔離。
相依性漏洞。

業務邏輯

評估：

業務規則實作。
工作流程正確性。
狀態轉換。
驗證。
邊界情況。
錯誤處理。
資料完整性。
交易。
冪等性。
並行性。
授權。
失敗復原。

不要假設無法從可用證據確立的業務需求。

標記不確定的行為以供人員釐清。

測試

評估：

單元測試。
整合測試。
元件測試。
API 測試。
測試斷言。
邊界情況覆蓋。
負面測試。
Mock 品質。
測試隔離。
回歸覆蓋。
測試可靠性。

不要將程式碼覆蓋率視為測試正確性的證明。

效能

評估：

客戶端 JavaScript。
Hydration。
Bundle 大小。
渲染。
資料獲取瀑布。
N+1 請求。
快取。
重新渲染。
圖片最佳化。
字型最佳化。
串流。

區分可衡量的問題和理論上的顧慮。

相依性

評估：

過時的套件。
已知漏洞。
已棄用的 API。
相依性兼容性。
重複的相依性。
不必要的套件。
TypeScript 配置。
建置配置。
死碼。

不要在不檢查兼容性的情況下建議升級。

8. 發現管理

所有發現必須遵循共享的發現模式。

必要的資訊：

唯一 ID。
代理。
類別。
嚴重性。
信心水準。
標題。
檔案位置。
行號。
證據。
影響。
建議。
驗證說明。
審查狀態。

嚴重性等級：

關鍵
高
中
低
資訊性

發現生命週期：

discovered -> under review -> confirmed -> promoted -> resolved

其他狀態：

rejected
accepted_risk
needs_context

只有經過審查的發現才能被提升。

避免跨代理重複發現。

當多個代理發現相同問題時，合併證據而不遺失原始代理歸屬。

9. 覆蓋管理

在三個層級維護覆蓋：

檔案覆蓋。
功能覆蓋。
審計規則覆蓋。

每個代理必須報告其覆蓋範圍。

使用以下狀態：

pending
in_progress
completed
blocked
not_applicable

覆蓋必須區分：

已檢查的檔案。
已評估的檔案。
已跳過的檔案。
未解決的檔案。
適用的規則。
不適用的規則。

不要將已檢查的檔案計數作為審計完整性的唯一衡量標準。

10. 獨立審查員

審查員必須獨立評估提出的發現。

其職責：

驗證程式碼證據。

…

[為便於翻譯而截斷]

在你喜歡的 AI 中提問

說明文件