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/ArchonScopeAnalyzing: [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 MarkersLocationMarkerStatusRecommendationPositive Examples[Well-written comments as good patterns]SummaryCategoryCountOverall 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 中内联定义子 AgentClaude 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在以下时机最有效生成文档之后——文档与代码最容易在此刻脱节立即审计可避免把错误写进提交含注释变更的 PR 合入之前——拦截改行为忘改注释的典型腐烂源例行注释腐烂巡检——对存量代码做定期体检清理 TODO 堆积与过时版本说明。4. 典型的调用会话你请用 comment-analyzer 审计当前未暂存变更中的注释。 主 Agent→ Task(subagent_typecomment-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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考