Skip to content

[skip deploy] docs(agents): specify Chinese PR descriptions - #118

Merged
yurenju merged 2 commits into
mainfrom
docs/pr-description-zh
Aug 18, 2026
Merged

[skip deploy] docs(agents): specify Chinese PR descriptions#118
yurenju merged 2 commits into
mainfrom
docs/pr-description-zh

Conversation

@yurenju

@yurenju yurenju commented Aug 18, 2026

Copy link
Copy Markdown
Contributor

使用者遇到的問題

看 PR 的人拿到的敘述語言不固定。AGENTS.md 的語言規則規定 commit message 與 issue/PR 標題用英文,但沒有規定 PR 內文,所以同一個 repo 的 PR 內文有中文也有英文。

還有一件更麻煩的:## PR 敘述怎麼寫 那一段對 Claude Code 來說根本不存在。

背景

這個 repo 的 CLAUDE.mdAGENTS.md 是兩份獨立的檔案,內容大致相同。Claude Code 讀 CLAUDE.md,Codex 讀 AGENTS.md。上一個 PR(#117)把 ## PR 敘述怎麼寫 只加進 AGENTS.mdCLAUDE.md 沒有跟著改,兩份就此分岔。

問題出在哪裡

git show main:CLAUDE.md 出來的第一段是這樣:

- 對話、討論、解釋:繁體中文
- README.md / DEVELOPER.md / CLAUDE.md:以中文為主,…
- docs/superpowers/ 下的所有文件(spec、plan、研究筆記等):…
- 程式碼、程式碼註解、commit message、issue/PR 標題、log 訊息字串:英文

整份 48 行裡沒有 ## PR 敘述怎麼寫AGENTS.md 有,CLAUDE.md 沒有。平常看不出來是因為兩份檔案內容幾乎一樣,diff 只有在改動之後才會分開,而改動當下沒有人會同時打開兩份對照。

修法

語言規則加一條,把內文與標題分開:

- PR 敘述(body):繁體中文。技術術語、錯誤訊息、路徑、程式碼區塊保留英文原文。PR 標題維持英文(見上一條)

標題維持英文,因為它跟 conventional commit 格式綁在一起,也是之後在 GitHub 上被搜尋的那一行。## PR 敘述怎麼寫 開頭再寫一次同一件事:只寫在語言規則清單裡,寫 PR 的 agent 不一定會讀到那一段。

第二個 commit 把 CLAUDE.md 換成指向 AGENTS.md 的 symlink,跟 wspc 一致,並在 AGENTS.md 開頭註明哪一份是正本。這一步看起來跟這次的改動無關,但省掉的話這次加的規則對 Claude Code 一樣看不到,等於白做。

刪掉的 CLAUDE.md 內容確認過沒有 AGENTS.md 缺的東西:唯一的差異是 README.md / DEVELOPER.md / CLAUDE.md 那一行在 AGENTS.md 版本結尾多了 / AGENTS.md

這個 PR 不修什麼

沒有幫既有的 PR 補中文敘述,只規範之後開的。

這個 repo 沒有驗收報告那套設定(沒有 .claude/rules/acceptance-report.md,也沒有 docs/acceptance-reports/),所以沒有加「PR 要連驗收報告」那一條。有那套設定的是 wspc,對應的 PR 是 sadcoderlabs/wspc#1121

測試

文件改動,沒有測試。手動確認 CLAUDE.md 換成 symlink 之後讀得到 AGENTS.md 的完整內容,且 git 記錄的 mode 是 120000

@yurenju
yurenju merged commit 93b7188 into main Aug 18, 2026
2 checks passed
@yurenju
yurenju deleted the docs/pr-description-zh branch August 18, 2026 08:56
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant