Claude Doctor 診斷 Claude Agent 行為問題並自動生成 CLAUDE.md 規則

Claude Doctor 診斷 Claude Agent 行為問題並自動生成 CLAUDE.md 規則。

專案介紹
Claude Doctor 是一款工具，能分析使用者 ~/.claude/ 資料夾中的對話記錄，偵測 Claude Agent 的行為反模式，並從歷史記錄生成可直接貼入 CLAUDE.md 或 AGENTS.md 的規則，讓 Agent 不再重蹈覆轍。

安裝與使用
透過 npm 安裝或直接執行，即可快速啟用診斷功能。

• npm i -g claude-doctor：全域安裝。
• npx claude-doctor：直接執行，預設分析所有工作階段。
  支援多種指令選項：
• claude-doctor <session-id>：檢查特定工作階段。
• claude-doctor <path/to.jsonl>：分析特定 jsonl 檔案。
• claude-doctor -p myproject：過濾特定專案。
• claude-doctor --rules：生成 CLAUDE.md / AGENTS.md 規則。
• claude-doctor --save：儲存模型至 .claude-doctor/ 資料夾。
• claude-doctor --json：以 JSON 格式輸出。

結構性訊號偵測
工具針對工作階段結構問題進行精準偵測，揭露 Claude Agent 的低效模式：

• edit-thrashing：單一工作階段內同一檔案被編輯 5 次以上。
• error-loop：連續 3 次以上工具失敗卻未改變方法。
• excessive-exploration：讀取與編輯比例超過 10:1。
• restart-cluster：30 分鐘內啟動多個工作階段。
• high-abandonment-rate：多數工作階段使用者訊息少於 3 條。

行為性訊號偵測
聚焦使用者互動模式，暴露 Agent 引發的挫折循環：

• correction-heavy：20% 以上使用者訊息以 "no"、"wrong"、"wait" 開頭。
• keep-going-loop：使用者反覆說 "keep going" / "continue"。
• repeated-instructions：5 輪內重複相同指示（Jaccard 相似度 >60%）。
• negative-drift：訊息逐漸變短且更偏向修正。
• rapid-corrections：使用者在 Agent 輸出後 10 秒內回應。
• high-turn-ratio：使用者每 Agent 回應發送 1.5 倍以上訊息。

詞彙性訊號偵測
使用 AFINN-165 情緒評分，結合自訂 Agent token（如 undo、revert、wrong、broken），量化負面語言趨勢，精準捕捉 Agent 失控的語言指標。

規則生成功能
執行 --rules 後，從歷史記錄自動產生即貼即用規則，例如基於 838 個工作階段分析的輸出：

## Rules (auto-generated by claude-doctor)

Based on analysis of 838 sessions. Paste into your CLAUDE.md or AGENTS.md.

- Read the full file before editing. Plan all changes, then make ONE complete edit.
- After 2 consecutive tool failures, stop and change your approach entirely.
- When the user corrects you, stop and re-read their message.
- Complete the FULL task before stopping.
- Every few turns, re-read the original request to make sure you haven't drifted.

這直接解決 Agent 的反覆錯誤與漂移問題。

模型儲存與開發
--save 會在 .claude-doctor/ 產生：

• model.json：訊號基準與專案設定檔。
• guidance.md：Agent 可讀規則，適用於 hooks 或 CLAUDE.md。
  開發流程簡單：pnpm install、pnpm build、pnpm test，採用 MIT 授權。

此工具直指 Claude Agent 在實際使用中的痛點，如無止盡編輯與修正循環，透過資料驅動診斷，提供實戰解方，避免使用者浪費時間在重複教訓上。