# 開發守則

本文檔為 AI Agent 在 `code-task-manager` 專案中執行開發任務的專用規範。

## 1. 專案概述

- **專案名稱**: `code-task-manager`
- **目的**: 一個為 AI Agents 設計的任務管理工具，強調思維鏈、反思和風格一致性。它將自然語言轉換為結構化的開發任務，並具有依賴追蹤和迭代優化功能。
- **技術棧**:
  - 主要語言: TypeScript
  - 執行環境: Node.js (ES Module)
  - 主要框架/函式庫: Express.js (用於可能的 API 或 WebGUI), Zod (用於資料驗證)
  - 套件管理器: npm
- **核心功能**:
  - 自然語言任務解析
  - 結構化任務生成與管理
  - 任務依賴關係追蹤
  - 任務執行與驗證輔助
  - 與 AI Agent 的思維流程整合

## 2. 專案架構

- **主要原始碼目錄**: `src/`
  - `src/index.ts`: 主要應用程式入口或模組匯出點。**修改此檔案需謹慎評估影響範圍。**
  - `src/utils/`: 通用工具函式。
  - `src/types/`: TypeScript 型別定義。**新增或修改型別時，務必確保與 Zod schema (如適用) 一致性。**
  - `src/tools/`: 專案特定工具或與外部服務整合的模組。
    - `src/tools/task/`: 任務管理相關工具實現，包含Planning Workflow工具。
      - **Planning Workflow工具**: `detailAnalyzeProblem.ts`, `systematicReadContent.ts`, `deepAnalyzeProblem.ts`, `comprehensiveThinkSolution.ts`, `gradualTrySolution.ts`, `detailRecordProcess.ts`
    - `src/tools/project/`: 專案管理工具，包含專案規則初始化。
    - `src/tools/research/`: 研究模式工具實現。
    - `src/tools/thought/`: 思維處理工具實現。
  - `src/models/`: 資料模型定義 (可能與 Zod schemas 相關)。
  - `src/prompts/`: AI 互動相關的提示詞模板。**修改或新增提示詞時，需考慮對 AI Agent 行為的潛在影響。**
    - `src/prompts/templates_en/`: 英文提示詞模板。
    - `src/prompts/templates_zh/`: 中文提示詞模板。
    - `src/prompts/generators/`: 提示詞生成器。
  - `src/public/`: WebGUI 或其他靜態資源。
  - `src/web/`: Web 服務器相關實現。
  - `src/tests/`: 單元測試和整合測試。
- **編譯輸出目錄**: `dist/` (此目錄由 `tsc` 自動生成，**禁止手動修改此目錄內容**)。
- **設定檔**:
  - `package.json`: 專案依賴和腳本。**新增依賴後，必須執行 `npm install`。**
  - `tsconfig.json`: TypeScript 編譯設定。**非必要情況下，禁止修改 `"strict": true` 設定。**
  - `.env.example` & `.env`: 環境變數設定。**敏感資訊不得提交至版本控制。**
- **外部工具**:
  - `tools/task-viewer/`: 基於 React 的任務查看器工具。**修改此工具時需確保與主專案的資料格式相容。**
- **文件**:
  - `README.md`: 主要專案說明文件。
  - `docs/en/README.md`: 英文版專案說明文件。**修改 README.md 時必須同步更新此檔案。**
  - `docs/`: 可能包含更詳細的架構、API 文件等。
  - `CHANGELOG.md`: 版本變更紀錄。**每次發布新版本前必須更新。**
  - `shrimp-rules.en.md`: 英文版開發守則。**修改 shrimp-rules.md 時必須同步更新此檔案。**
  - `data/WebGUI.md`: 包含 Task Manager UI 的連結。

## 3. 程式碼規範

### 3.1. 命名規範

- **變數與函式**: 使用小駝峰命名法 (camelCase)。
  - _範例 (可做)_: `const taskName = "example"; function processTask() {}`
  - _範例 (不可做)_: `const Task_Name = "example"; function Process_Task() {}`
- **類別與介面**: 使用大駝峰命名法 (PascalCase)。
  - _範例 (可做)_: `class TaskManager {}; interface ITaskOptions {}`
  - _範例 (不可做)_: `class taskManager {}; interface iTaskOptions {}`
- **檔案名稱**: 使用小駝峰命名法或橫線連接 (kebab-case) 的 `.ts` 檔案。
  - _範例 (可做)_: `taskProcessor.ts`, `task-utils.ts`
  - _範例 (不可做)_: `TaskProcessor.ts`, `task_utils.ts`
- **常數**: 使用全大寫蛇形命名法 (UPPER_SNAKE_CASE)。
  - _範例 (可做)_: `const MAX_RETRIES = 3;`
  - _範例 (不可做)_: `const maxRetries = 3;`

### 3.2. 格式要求

- **縮排**: 使用 2 個空格進行縮排。**禁止使用 Tab 字元。**
- **分號**: 每行敘述句尾必須加上分號。
- **引號**: 字串優先使用單引號 (`'`)，除非字串本身包含單引號。
  - _範例 (可做)_: `const message = 'Hello World'; const complex = "It\\'s complex";`
  - _範例 (不可做)_: `const message = "Hello World";`
- **最大行長度**: 建議不超過 120 字元。
- **註解**:
  - 單行註解使用 `//`。
  - 多行註解使用 `/* ... */`。
  - JSDoc 風格的註解應用於公開的函式、類別和方法。
    - _範例 (可做)_:
      ```typescript
      /**
       * Processes a given task.
       * @param taskId The ID of the task to process.
       * @returns True if successful, false otherwise.
       */
      function processTaskById(taskId: string): boolean {
        // implementation
        return true;
      }
      ```

### 3.3. TypeScript 特定規範

- **型別註解**: 所有函式參數、回傳值和變數宣告都應有明確的型別註解。**禁止使用 `any` 型別，除非在極特殊且無法避免的情況下，並需加上註解說明原因。**
  - _範例 (可做)_: `function greet(name: string): string { return \`Hello, ${name}\`; }`
  - _範例 (不可做)_: `function greet(name): any { return "Hello, " + name; }`
- **介面與型別別名**: 優先使用介面 (Interface) 定義物件的形狀，使用型別別名 (Type Alias) 定義聯合型別、元組或其他複雜型別。
- **ES Module**: 使用 `import` 和 `export` 語法。
  - _範例 (可做)_: `import { Task } from './models/task'; export class TaskService {}`
  - _範例 (不可做)_: `const Task = require('./models/task'); module.exports = TaskService;`
- **嚴格模式**: 專案已啟用 `"strict": true`。必須解決所有 TypeScript 的嚴格模式錯誤。

## 4. 功能實作規範

### 4.1. 通用原則

- **單一職責原則 (SRP)**: 每個函式和類別應只負責一項功能。
- **保持簡潔 (KISS)**: 避免過度複雜的解決方案。
- **重複利用**: 盡可能將通用邏輯抽取為可重用函式或類別，存放於 `src/utils/` 或相關模組。
- **錯誤處理**:
  - 使用 `try...catch` 處理預期內的錯誤。
  - 對於關鍵操作，應提供清晰的錯誤訊息。
  - 考慮使用自定義錯誤類別以提供更豐富的錯誤資訊。
- **日誌記錄**:
  - 在關鍵操作、錯誤處理和重要狀態變更時加入日誌記錄。
  - 考慮使用結構化日誌。
  - **禁止在日誌中記錄敏感資訊 (如密碼、API Keys)。**

### 4.2. Zod 使用

- 位於 `src/models/` 或 `src/types/` 的資料結構定義，應優先使用 Zod schema 進行定義和驗證。
- Zod schema 應與 TypeScript 型別保持同步。可使用 `z.infer<typeof schema>` 生成型別。

  - _範例 (可做)_:

    ```typescript
    import { z } from "zod";

    export const TaskSchema = z.object({
      id: z.string().uuid(),
      name: z.string().min(1),
      description: z.string().optional(),
    });

    export type Task = z.infer<typeof TaskSchema>;
    ```

### 4.3. Express.js 使用 (若有 API/WebGUI)

- 路由定義應清晰且遵循 RESTful 原則 (若為 API)。
- 中介軟體 (Middleware) 應有效組織，例如錯誤處理中介軟體、日誌中介軟體等。
- 所有外部輸入 (request parameters, body, query) **必須**經過 Zod 或類似機制驗證。

### 4.4. 研究模式開發規範

- **研究狀態管理**: 研究模式工具必須維護研究狀態的連續性，包括 `previousState`、`currentState` 和 `nextSteps`。
- **主題專注性**: 實現機制確保研究不偏離主題，通過 `nextSteps` 參數約束研究方向。
- **多源整合**: 研究工具應結合網路搜尋和程式碼庫分析，提供全面的技術調查。
- **狀態持久化**: 研究進度和發現應自動保存，支援跨會話的研究連續性。

### 4.5. 思維處理工具規範

- **階段化思考**: 思維工具必須支援不同的思考階段，包括問題定義、資訊收集、分析、綜合等。
- **標籤系統**: 實現標籤機制來分類和組織思維內容，便於後續檢索和分析。
- **公理追蹤**: 記錄使用的公理和挑戰的假設，確保推理過程的透明性。
- **動態調整**: 支援動態調整思維總數和方向，適應複雜問題的需求變化。

### 4.6. 任務查看器整合規範

- **資料格式相容**: 任務查看器必須與主專案的任務資料格式完全相容，特別是 `taskModel.ts` 中定義的結構。
- **即時更新**: 支援任務狀態的即時更新和顯示，確保資料同步性。
- **多配置支援**: 支援多個配置文件的管理，實現專案隔離和靈活配置。
- **效能優化**: 針對大量任務資料進行效能優化，確保流暢的使用體驗。

### 4.7. Planning Workflow 工具開發規範

- **工具模板結構**: 每個Planning Workflow工具必須包含完整的模板結構：
  - 主模板文件 (`index.md`)：包含完整的工具提示詞和參數注入點
  - 工具描述文件 (`toolsDescription/[toolName].md`)：提供工具功能的詳細描述
- **生成器函數規範**:
  - **必須**包含完整的TypeScript接口定義，包括 `memoryDir?: string` 參數
  - **必須**實現參數驗證和默認值處理
  - **必須**使用 `generatePrompt` 函數進行模板變量注入
- **MCP工具實現規範**:
  - **必須**導出工具函數和對應的Zod schema
  - **必須**在 `src/tools/task/index.ts` 中正確導出
  - **必須**在 `src/index.ts` 中註冊工具描述和處理邏輯
- **參數設計原則**:
  - 支援靈活的參數配置，適應不同使用場景
  - 提供合理的默認值，降低使用門檻
  - 包含可選的 `memoryDir` 參數以支持記憶功能
- **多語言模板要求**:
  - **嚴格要求**：新增Planning Workflow工具時，**必須**同時創建中英文版本的模板
  - **當前狀態**：英文版Planning Workflow工具模板缺失，需要補充

## 5. 框架/外掛程式/第三方庫使用規範

- **新增依賴**:
  - **必須**先評估依賴的必要性、維護狀態和安全性。
  - 使用 `npm install <package-name>` (用於執行依賴) 或 `npm install --save-dev <package-name>` (用於開發依賴)。
  - **必須**在 `package.json` 中指定明確的版本範圍 (例如 `^1.2.3` 或 `~1.2.3`)，避免使用 `*`。
- **更新依賴**: 定期檢查並更新依賴至最新穩定版本，以獲取安全性修補和新功能。更新前需評估潛在的破壞性變更。
- **移除依賴**: 若不再需要某個依賴，使用 `npm uninstall <package-name>` 將其移除，並從程式碼中移除相關引用。

## 6. 工作流程規範

### 6.1. 開發流程

1.  **理解任務**: 仔細閱讀任務描述、需求和驗收標準。
2.  **分支管理**: 從最新的 `main` (或 `develop`) 分支建立新的特性分支 (feature branch)。分支名稱應簡潔明瞭，例如 `feature/add-task-editing` 或 `fix/login-bug`。
3.  **編碼與測試**:
    - 按照本規範進行編碼。
    - **必須**為新功能或修復的 bug 編寫單元測試 (存放於 `src/tests/`)。
    - 執行 `npm run build` 確保程式碼可以成功編譯。
    - 本地執行 `npm run dev` 或 `npm run start` 進行測試。
4.  **程式碼提交**:
    - Git commit message 應遵循 Conventional Commits 規範 (例如 `feat: add user authentication`, `fix: resolve issue with task sorting`)。
    - **禁止提交包含 `console.log` 或其他偵錯訊息的程式碼至主要分支。**
5.  **Pull Request (PR)**:
    - 將特性分支推送到遠端倉庫，並建立 Pull Request 至 `main` (或 `develop`) 分支。
    - PR 描述應清晰說明變更內容和原因。
6.  **Code Review**: 等待其他開發者或 AI Agent 進行 Code Review。
7.  **合併與部署**: Code Review 通過後，合併 PR。部署流程依專案設定。

### 6.2. 版本控制 (Git)

- **主要分支**:
  - `main`: 代表穩定且可部署的產品版本。
  - `develop` (若使用): 代表開發中的最新版本。
- **提交頻率**: 建議小步快跑，頻繁提交有意義的變更。
- **解決衝突**: 合併或 rebase 分支時，若發生衝突，**必須**仔細解決，確保程式碼的正確性和完整性。

### 6.3. CHANGELOG 更新

- 在發布新版本之前，**必須**更新 `CHANGELOG.md`。
- 紀錄應包含版本號、發布日期以及新增功能、修復的錯誤和重大變更列表。

## 7. 關鍵檔案交互規範

- **修改 `src/types/` 或 `src/models/` (特別是 Zod schemas)**:
  - **必須**檢查並更新所有引用到這些型別或 schema 的檔案，確保型別一致性。
  - **必須**重新執行相關測試。
- **修改 `src/index.ts`**:
  - 若修改了模組的匯出 API，**必須**檢查所有依賴此模組的專案或檔案，並進行相應調整。
- **修改 `package.json` (特別是 `dependencies` 或 `scripts`)**:
  - **必須**通知團隊成員或相關 AI Agent 執行 `npm install`。
  - 若修改 `scripts`，需確保 CI/CD 流程 (若有) 也相應更新。
- **修改 `.env.example`**:
  - **必須**同步更新所有開發環境的 `.env` 檔案，並通知團隊成員。
- **多語言模板同步規範**:
  - **修改 `src/prompts/templates_en/` 中的任何模板時**，**必須**同步更新對應的 `src/prompts/templates_zh/` 中的模板。
  - **修改 `src/prompts/templates_zh/` 中的任何模板時**，**必須**同步更新對應的 `src/prompts/templates_en/` 中的模板。
  - **新增工具模板時**，**必須**同時在兩個語言目錄中創建對應的模板文件。
- **文檔多語言同步規範**:
  - **修改 `README.md` 時**，**必須**同步更新 `docs/en/README.md`。
  - **修改 `shrimp-rules.md` 時**，**必須**同步更新 `shrimp-rules.en.md`。
  - **修改 `docs/zh/` 中的任何文檔時**，**必須**同步更新對應的 `docs/en/` 中的文檔。
- **任務查看器工具規範**:
  - **修改 `src/models/taskModel.ts` 中的任務資料結構時**，**必須**檢查並更新 `tools/task-viewer/` 中的相關組件以確保相容性。
  - **修改任務狀態或屬性時**，**必須**確保任務查看器能正確顯示新的狀態或屬性。
- **修改 `README.md` 或 `docs/` 內的文檔**:
  - 若變更涉及核心功能或使用方式，**必須**確保文件內容的準確性和即時性。

## 8. AI 決策規範

### 8.1. 處理模糊請求

- 當收到模糊的開發指令時 (例如 "優化任務列表顯示")：
  1.  **嘗試澄清**: 若可能，向用戶或任務發起者請求更具體的細節或預期結果。
  2.  **分析上下文**: 檢查相關程式碼 (`src/`)、現有 UI (若有)、相關 issue (若有) 來推斷可能的意圖。
  3.  **提出方案**: 基於分析，提出 1-2 個具體的實施方案，並說明各自的優缺點及預計工作量。
  4.  **等待確認**: 在獲得明確指示前，不進行大規模程式碼修改。

### 8.2. 錯誤/異常處理策略

- **優先級**:
  1.  **使用者體驗**: 避免程式崩潰，提供友好的錯誤提示。
  2.  **資料完整性**: 確保錯誤不會導致資料損壞或不一致。
  3.  **系統穩定性**: 記錄詳細錯誤資訊以供排查。
- **選擇**:
  - 對於可預期的錯誤 (例如使用者輸入無效)，應在該操作的上下文中處理並給予提示。
  - 對於意外的系統錯誤，應捕獲、記錄，並可能向上拋出或觸發全域錯誤處理機制。

### 8.3. 依賴選擇

- 當需要引入新的第三方函式庫時：
  1.  **檢查現有**: 確認專案中是否已有可滿足需求的類似函式庫。
  2.  **評估選項**:
      - **活躍度與社群支援**: 選擇維護良好、社群活躍的函式庫。
      - **輕量級**: 避免引入過於龐大或功能冗餘的函式庫。
      - **安全性**: 檢查是否有已知的安全漏洞。
      - **授權條款 (License)**: 確保與專案授權相容。
  3.  **最小化原則**: 僅引入確實需要的函式庫。

## 9. 禁止事項

- **禁止直接修改 `dist/` 目錄下的任何檔案。** 該目錄為編譯產物。
- **禁止在未執行 `npm install` 的情況下，假定新依賴可用。**
- **禁止在主要分支 (`main` 或 `develop`) 直接提交未經測試或未完成的程式碼。** 必須使用特性分支。
- **禁止提交包含 API Keys、密碼或其他敏感資訊的程式碼至版本控制系統。** 使用 `.env` 檔案管理此類資訊。
- **禁止在未告知或未獲同意的情況下，大幅修改核心架構或公共 API。**
- **禁止忽略 TypeScript 的型別錯誤。** 必須解決所有 `tsc` 報告的錯誤。
- **禁止在沒有充分理由和註解的情況下使用 `any` 型別。**
- **禁止在程式碼中留下大量的 `console.log` 或其他臨時偵錯程式碼。**
- **禁止在未更新 `CHANGELOG.md` 的情況下發布新版本。**
- **禁止引入與專案 MIT 授權條款不相容的第三方函式庫。**
- **多語言同步禁止事項**:
  - **禁止只修改一種語言的模板而不同步更新另一種語言的對應模板。**
  - **禁止只修改一種語言的文檔而不同步更新另一種語言的對應文檔。**
  - **禁止在新增工具時只創建單一語言的模板文件。**
  - **緊急修復要求**：**禁止繼續使用缺少英文版本的Planning Workflow工具模板，必須立即補充英文版本。**
- **任務查看器相關禁止事項**:
  - **禁止修改任務資料結構而不檢查任務查看器的相容性。**
  - **禁止在任務查看器中硬編碼任務狀態或屬性值。**
- **Planning Workflow工具禁止事項**:
  - **禁止在生成器函數中缺少 `memoryDir?: string` 參數定義。**
  - **禁止在工具實現中缺少對應的Zod schema導出。**
  - **禁止在新增Planning Workflow工具時不在 `src/index.ts` 中註冊工具描述和處理邏輯。**
  - **禁止修改Planning Workflow工具模板而不同步更新工具描述文件。**
  - **禁止在Planning Workflow工具中使用硬編碼的參數值，必須支援動態配置。**

## 10. 更新此規範文件 (`shrimp-rules.md`)

- 當專案的技術棧、核心架構、主要工作流程或重要規範發生變動時，**必須**同步更新此文件。
- 更新請求應明確指出需要變更的章節和內容。
- 若收到模糊的 "更新規則" 指令，AI Agent **必須**：
  1.  自主分析當前程式碼庫的變更 (例如 `git diff`、最近的 commit)。
  2.  比較現有的 `shrimp-rules.md` 與專案現狀，找出不一致或過時的規則。
  3.  在 `process_thought` 階段列出推斷的更新點及其理由。
  4.  提出具體的修改建議，或直接編輯此文件。
  5.  **嚴格禁止**在執行自主分析前就模糊請求向用戶尋求澄清。

---

此開發守則旨在確保 AI Agent 能夠高效、一致且安全地參與 `code-task-manager` 專案的開發。
