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>
58 lines
2.8 KiB
Markdown
58 lines
2.8 KiB
Markdown
# 實作規範
|
||
|
||
改目標專案的程式碼時照這份做。這份規則只存在於本 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 設定與相依版本，除非待辦本身就是在做那件事。
|
||
- 既有程式碼的註解不符合這份規範時，**只補你改到的那些**，不要順手重寫整個檔案。
|