jiantw83andClaude Opus 5
6e0fa92e73
兩份規則只存在於本 plugin 裡，由流程正本指名讀取，不寫進目標專案的任何檔案。 coding-standards.md 管規則：六種專案檔對應語言、認不出就停下來問；分層看職責不看目錄， 三層各寫功能／邏輯／資料源註解，服務層要標註呼叫的方法讓 reviewer 追得到呼叫鏈； 屬性的用途註解遞迴到每一層，並附真實資料範例，優先取自 MCP，推理來的要明講未經驗證 ——不註明的話，會有人照著沒對過的格式寫解析。 comment-styles.md 只管格式：六種語言各一節，都附可照抄的方法註解與屬性註解範例。 Go 的「以識別字開頭」與 Python 的「docstring 在定義的下一行」各自點名，那是最常被 照抄成別的語言寫法的兩處。 Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2.8 KiB
2.8 KiB
實作規範
改目標專案的程式碼時照這份做。這份規則只存在於本 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）。
範例的來源有優先順序：
- 優先從 MCP 取得——能連到真實資料來源時，取真的值。
- 取不到就以邏輯推理，並明確註明「由邏輯推理、未經驗證」。
註明這件事不能省。未經驗證的範例本身有用，但讓人誤以為它經過驗證就會出事—— 有人會照著那個格式寫解析。
邊界
- 不改與這次待辦無關的程式碼。看到順手想修的東西，記下來、說出來，不要摸進這次的變更裡。
- 不動目標專案的設定檔、CI 設定與相依版本，除非待辦本身就是在做那件事。
- 既有程式碼的註解不符合這份規範時，只補你改到的那些，不要順手重寫整個檔案。