Comment Analysis: [Scope Description]

Comment Analysis: [Scope Description]

【免费下载链接】ArchonThe first open-source harness builder for AI coding. Make AI coding deterministic and repeatable.项目地址: https://gitcode.com/GitHub_Trending/archon3/Archon

Scope

• Analyzing: [scope]
• Comment count: [N comments analyzed]

Critical Issues (Must Fix)

[Inaccurate/misleading comments with evidence]

Improvement Opportunities

[Comments that would benefit from enhancement]

Recommended Removals

[Comments that add no value]

Stale Markers

Positive Examples

[Well-written comments as good patterns]

Summary

Overall Assessment: [GOOD / NEEDS ATTENTION / SIGNIFICANT ISSUES]

各区块的用途： - **Scope**：声明审计范围与注释总数，让读者知道这份报告覆盖了什么； - **Critical Issues (Must Fix)**：不准确或误导性的注释，每条必须附证据（代码引用）； - **Improvement Opportunities**：值得增强的注释； - **Recommended Removals**：无价值的注释（对应价值评估中的 Low 档）； - **Stale Markers**：用表格逐条列出 TODO/FIXME 等标记的位置、状态与处置建议； - **Positive Examples**：挑出写得好的注释作为正面样板——这让报告不只是"挑刺"，还能沉淀团队注释规范； - **Summary**：按类别计数，并给出整体评估等级 GOOD / NEEDS ATTENTION / SIGNIFICANT ISSUES。 这一"问题分级 + 证据 + 正面样例 + 汇总评级"的结构，在 Archon 的评审体系中是标准做法——[code-reviewer.md](https://link.gitcode.com/i/8ab3eda4028b82e0f410d619063f70dc) 同样采用"Critical/Important + 置信度评分 + 证据引用 + Verdict"的报告形态，便于主 Agent 或人类维护者快速决策。 --- ## 四项关键原则：让审计结论可信 - **Skepticism first（怀疑优先）**——在核验之前，先假定注释可能是错的。这是防止"注释看着合理就放行"的心理防线； - **"Why" over "what"（重"为什么"轻"是什么"）**——优先保留解释意图的注释，对应 Archon "Do not narrate the code" 的工程规范； - **Evidence-based（证据驱动）**——每条 issue 都必须有代码引用作为证明，没有证据的发现不算发现； - **Advisory only（只读建议）**——只报告问题，不亲自修复；修复动作留给主 Agent 或开发者，保持"评审权"与"修改权"分离。 --- ## 在 Archon 中如何落地使用 ### 1. 作为 `.claude/agents/` 磁盘级子 Agent `comment-analyzer` 与仓库中的 [code-reviewer.md](https://link.gitcode.com/i/8ab3eda4028b82e0f410d619063f70dc)、[code-simplifier.md](https://link.gitcode.com/i/4f5b37c9fdad57de773ed9e6bbf9142e)、[triage-agent.md](https://link.gitcode.com/i/744bae00ceffa2e796c64f578ca18d9d) 等一起放在 `.claude/agents/` 目录下，属于**磁盘级、跨工作流复用**的子 Agent：它们位于 workflow YAML 之外，会被 Claude Agent SDK 自动发现，任何主 Agent 都可以通过 `Task(subagent_type=...)` 按名调用。 Archon 的文档明确给出了选择依据（见 [authoring-workflows.md](https://link.gitcode.com/i/b343c442808e1a5ed7aed8d829c12095) 的 "When to use `agents:` vs `.claude/agents/*.md` files" 一节）： - **`.claude/agents/*.md`（磁盘级）**——当子 Agent 被多个工作流或整个项目共享时使用，例如多个维护工作流共用的审计型 Agent； - **`agents:`（工作流内联）**——当子 Agent 只服务于某一个工作流时使用，随 YAML 一起分发。 ### 2. 作为 `agents:` 内联子 Agent 的思想来源 如果你只想在**单个工作流**的某个 DAG 节点里做注释审计，Archon 还支持直接在 YAML 中内联定义子 Agent（Claude only），例如： ```yaml nodes: - id: comment-audit prompt: | 对本节点范围内变更的代码注释做准确性、完整性与长期价值审计， 对每条问题附上证据引用，按 Critical / Improvement / Removal 分级输出。 model: sonnet allowed_tools: [Bash, Read] agents: comment-checker: description: 审计注释是否与代码行为一致，识别注释腐烂 prompt: | 你只读、只审计。逐条核验注释与实现的参数、返回值、行为、 边界情况、引用与示例；评估完整性；按价值分档；输出结构化报告。 model: sonnet tools: [Bash, Read]

内联定义时需注意：Agent ID 必须为 kebab-case（^[a-z0-9]+(-[a-z0-9]+)*$），description与prompt必填，model、tools、disallowedTools、skills、maxTurns可选；内联与磁盘级两种来源可共存，运行时会同时暴露给Task(subagent_type=...)。

3. 三个推荐的触发时机

按文档description的指引，comment-analyzer在以下时机最有效：

1. 生成文档之后——文档与代码最容易在此刻脱节，立即审计可避免把错误写进提交；
2. 含注释变更的 PR 合入之前——拦截"改行为忘改注释"的典型腐烂源；
3. 例行注释腐烂巡检——对存量代码做定期体检，清理 TODO 堆积与过时版本说明。

4. 典型的调用会话

你：请用 comment-analyzer 审计当前未暂存变更中的注释。 主 Agent：→ Task(subagent_type="comment-analyzer") comment-analyzer： 1. 运行 git diff，收集变更中的全部注释； 2. 按六项检查表核验事实准确性； 3. 评估完整性（前置条件、副作用、错误处理等）； 4. 按 High/Medium/Low/Negative 分档评估长期价值； 5. 识别腐烂信号，输出《Comment Analysis》报告。 你：→ 依据报告中的 Critical Issues，逐一修正注释后再提交。

【免费下载链接】ArchonThe first open-source harness builder for AI coding. Make AI coding deterministic and repeatable.项目地址: https://gitcode.com/GitHub_Trending/archon3/Archon