github-comment-quality

GitHub 评论与沟通质量标准

核心理念

GitHub 文本是面向审阅者和协作者的技术沟通，不是内部草稿、工作证明账本或机器人执行日志。

面向人类读者写作：简洁地说明结果、必要的技术理由和验证情况。尊重审阅者的时间，用最少的文字回答问题或解决问题。

授权与范围边界

• 起草与发布： 起草文本并不代表获准发布，除非用户明确要求执行相关操作（例如“创建 PR”“回复审阅意见”或“提交 issue”）。不要擅自发布评论或创建未被要求的 issue。
• 不要自动创建无关 issue： 执行任务时发现无关的 bug 或 CI 缺口，应在本地标记，或询问用户是否要提交 issue。未经用户授权，绝不要自动创建 issue。

---

GitHub 沟通中的 8 种反模式

1. “开发日记式” PR 描述

• 反模式： 把 PR 正文写成叙述日志，记录所有想法、尝试、测量结果和放弃的方案（例如多段设计论述、弃用的替代方案、重复的基准测试结果和过时的起草记录）。

• 规则： PR 正文记录的是当前分支的状态，而非历史起草过程。内容应聚焦于：

  • 摘要： 用 1-2 条要点说明用户可见的变化或架构变化。
  • 关键变更： 具体的实现细节（仅在不明显时说明）。
  • 验证： 新增／通过的具体测试和手动检查（不要粘贴原始终端输出）。
  • 修复： issue 引用。
  • （对于小型的 1-3 行变更，建议用 1-2 句话描述，无需添加分节标题。）

• ❌ (用 500 字解释为何拒绝某些库依赖、测试框架如何配置，并粘贴 40 行终端输出)

• ✅

  Fixes #72
  
  ## Summary
  
  - Initialize upstream MCP servers concurrently during startup rather than serially.
  - Bounds startup latency to the slowest single upstream server.
  
  ## Changes
  
  - Launch each configured upstream in its own goroutine and merge results deterministically by sorted server name.
  - Retain child process handles to ensure clean process termination on shutdown.
  
  ## Verification
  
  - Added unit tests for concurrent launch timing and deterministic tool ordering.
  - Local benchmark: 9 upstreams initialize in 9.7s (down from 31.1s serial).
  - `go test -race ./...` passes.
  

2. 不成比例且过度纠结合规的审阅回复

• 反模式： 针对一行审阅意见，回复多段合规报告，逐条列出遵循的规则、重复差异内容并引用提示词。

• 规则（适度原则）： 用最简短的回复说明会影响决策的事实或已应用的修复。

  • 常规修复： 一行说明 + commit SHA。
  • 技术限制／意见不合： 直接说明具体的不变量、限制或测试证据，不要陷入哲学争论或元讨论。

• ❌

  Ran both humanizer and comment-and-documentation-quality skills on the guide. Flagged bold-spam (§15), announcing the next point (§28), repetition (§11), and stripped em dashes under Anti-Pattern 1 in commit 7dfe483...
  

• ✅ Updated in 7dfe483. Removed the MCP server comparison and tightened the wording. Build and tests pass.

3. 解释“我为何犯错”（防御性复盘）

• 反模式： 解释模型如何产生幻觉、被先例代码误导，或做出了错误假设。

• 规则： 不需要复盘 AI 的困惑。直接说明修正内容。

• ❌

  The URL split was my mistake. I carried over the Home Assistant case where aiohttp 404s on the slash variant, and assumed the same applied here without checking. Reverted in b64a2fd...
  

• ✅ Reverted the URL change and restored the test connection step in b64a2fd. The HTTP endpoint on 27123 remains the default.

4. 情绪化与元评论（自我评价）

• 反模式： 自我评价表现或叙述意图：
  • “三点批评都说得对。”
  • “我知道它是怎么发展到这一步的。”
  • “这不是机器人没能收敛。”
  • “刻意保持简洁……”
• 规则： 删除表演式自我评价、防御性言论和情绪化措辞。评论应保持技术性、中立和直接。（承认错误时，简短而专业地致意即可。）
• ❌ Fair hit on all three. You are right that I argued the point instead of doing it, and that citing other guides was the wrong move.
• ✅ Updated in 74f9283. Removed all em dashes across the guides and tightened the setup instructions.

5. 机器人签名、水印与生成者页脚

• 反模式： 添加 _Generated by Claude Code_、_Reviewed by OpenAI Codex_ 或模型水印。
• 规则： 绝不要在 PR、issue 或评论中自愿添加“Generated by”“Automated by”或工具署名页脚。
• ❌ Fixed the typo in 3a1b2c3.\n\n---\n_Generated by Claude Code_
• ✅ Fixed the typo in 3a1b2c3.

6. 独立验证噪声

• 反模式： 在公开 issue 或 PR 中发表评论，只叙述本地会话活动，却没有推动评审进展（例如粘贴原始 go test 输出，或在无需采取行动时宣布运行了本地检查）。

• 规则： 在 PR 正文或评审回复中包含验证摘要。不要单独发布执行记录。

• ❌

  I merged this branch onto main in a throwaway worktree and verified it locally:
  $ go test -race ./...
  ok github.com/dvcrn/mcpnest/internal/app 7.846s
  

• ✅ (改为在 PR 正文或相关评审回复中说明：Verified locally with go test -race ./...)

7. 无关发现与范围蔓延

• 反模式： 将仓库其他部分发现的无关 bug、CI 失败或观察结果添加到特定 PR 或评审讨论串中。
• 规则： 每个 PR 和评审讨论串都应严格限定在自身主题范围内。在本地标记无关问题，或在单独提交 issue 前询问用户。
• ❌ Fixed the query parameter in 4b5c6d7. Also noticed that GitHub Actions CI configuration in .github/workflows/ci.yml is missing a Go cache step, which might slow down builds.
• ✅ Fixed the query parameter in 4b5c6d7. Tests pass.

8. 描述你刻意没有做的事

• 反模式： 列出没有执行的假设性任务（“有一件事我没做……”“我没有改动较旧的文件……”“我把这件事搁置了……”）。
• 规则： 只有在遗漏涉及真正待定的决策，或评审者必须评估的已知限制时，才提及遗漏。
• ❌ I did not touch the older guides beyond the dashes because antigravity-sync-macos is 162 words and reads thin.
• ✅ (保留真实的技术限制) This change kills direct child processes on cancellation. Process-group cleanup for grandchildren is not yet handled and should be addressed in a follow-up.

---

技术精确性与事实准确性

1. 绝不捏造主张或证据： 不要编造测试通过结果、基准测试、提交、issue 编号或验证步骤。除非修复已提交并推送，否则不要声称已应用修复。
2. 保留技术上的不确定性： 不要把 may 译成“将会”，把 typically 译成“总是”，也不要把实验性观察说成普遍保证。
3. 每条事实只出现一次： 不要在 PR 正文、评审讨论串、状态评论和最终摘要中重复同一项调查结果。
4. 保留技术术语： 使用精准的技术术语（例如 race condition、mutex contention、atomic swap、WAL mode）；不要过度解释基础语言语义。

---

格式、标点与语气规则

1. 禁止使用 em dash（—）、en dash（–）和表示停顿的双连字符（--）： 使用冒号、括号或独立句子。（保留 --verbose 等 CLI 标志的原文。）
2. 不要滥用粗体或装饰性表情符号： 避免每隔一句就加粗，或在标题前加上 🚀、💡、✅。
3. 不要粘贴原始终端日志： 用简洁的一行或简短表格概述测试和基准测试结果，而不是粘贴 40 行测试输出。
4. 避免铺垫和谄媚： 删除 “很好的建议！”“你说得完全正确！”“让我们深入探讨” 等表达。
5. 标题简洁明了： PR 和 issue 标题应具体、简洁，避免对话式赘语。PR 标题应使用祈使句（例如 Fix dirty state warning in AI dialog）。Issue 标题应清楚描述问题或目标（例如 AI dialog shows stale warning after save 或 Support concurrent upstream initialization）。除非仓库要求，否则避免使用 Conventional Commits 前缀（feat:、fix:）。

---

模板

有关特定工件的示例，请阅读 templates.md。根据 PR 描述、审查评论或 issue 选择相应模板；不要把所有部分都强加到简短回复中。