# 實作規範

改目標專案的程式碼時照這份做。這份規則只存在於本 plugin 裡，**不寫入目標專案的任何檔案**
——目標專案的 `CLAUDE.md`、`AGENTS.md` 與設定檔一律不碰。

## 先認語言，再動手

改任何一個檔案之前，先從專案檔認出這是什麼語言：

| 專案檔 | 語言 |
| --- | --- |
| `*.csproj`、`*.sln` | C# |
| `composer.json` | PHP |
| `package.json` | JavaScript／TypeScript |
| `go.mod` | Go |
| `pom.xml`、`build.gradle` | Java |
| `pyproject.toml`、`setup.py` | Python |

認出來之後，對照 `references/comment-styles.md` 取得該語言的註解格式。

**認不出來就停下來問，不要猜。** 猜錯的代價是滿檔案格式不對的註解，比沒有註解更難清理。
同一個 repo 裡有多種語言時，以**正在改的那個檔案**所屬的語言為準。

## 分層看職責，不看目錄

目錄名稱會騙人：叫 `services/` 的資料夾裡常有一半是控制層。判斷依據一律是**這段程式在做什麼**。

| 層 | 怎麼認 | 要寫什麼註解 |
| --- | --- | --- |
| 控制層 | 對外的介面：HTTP handler、CLI 進入點、事件訂閱者、對外 API | **功能註解**——這個介面在做什麼、誰會呼叫它 |
| 服務層 | 所有邏輯：判斷、計算、流程編排 | **邏輯註解**——這段邏輯在解決什麼問題，並**標註它呼叫的所有方法** |
| 存取層 | 任何碰資料來源的東西：DB、外部 API、檔案、快取、訊息佇列 | **資料源註解**——資料從哪裡來、是哪一張表／哪一支 API |

服務層要標註呼叫的方法，是為了讓 reviewer **追得到呼叫鏈**：看一個方法就知道它會往下走到哪裡，
不必逐層點開。

## 屬性一律要有用途註解

每一個屬性都寫它的用途。**屬性本身是類別時遞迴處理**——巢狀結構的每一層都要有，
不能只註解最外層然後說「詳見該類別」。

用途註解要附**真實的資料範例**，讓人知道實際格式長什麼樣（是 `2026-09-17` 還是
`2026/09/17`，是 `TWD` 還是 `NTD`）。

範例的來源有優先順序：

1. **優先從 MCP 取得**——能連到真實資料來源時，取真的值。
2. 取不到就以邏輯推理，並**明確註明「由邏輯推理、未經驗證」**。

註明這件事不能省。未經驗證的範例本身有用，但讓人誤以為它經過驗證就會出事——
有人會照著那個格式寫解析。

## 邊界

- 不改與這次待辦無關的程式碼。看到順手想修的東西，記下來、說出來，不要摸進這次的變更裡。
- 不動目標專案的設定檔、CI 設定與相依版本，除非待辦本身就是在做那件事。
- 既有程式碼的註解不符合這份規範時，**只補你改到的那些**，不要順手重寫整個檔案。