Archon 提交前代码审查Code Review从 git diff 到高质量报告的完整实践指南【免费下载链接】ArchonThe first open-source harness builder for AI coding. Make AI coding deterministic and repeatable.项目地址: https://gitcode.com/GitHub_Trending/archon3/Archon本指南围绕 Archon 仓库内置的提交前代码审查命令.claude/commands/validation/code-review.md展开完整讲解如何对最近变更的代码进行系统化技术审查——从收集项目约定、定位 diff 范围到按六类维度逐项检查再到输出带严重级别和修复建议的结构化报告。读完本文你将掌握一套可直接复用的审查流程并理解审查结论背后对应的源码约定与验证命令。命令定位一次结构化的 Pre-Commit 质量检查该命令的文件头frontmatter给出了它的定位description: Technical code review for quality, bugs, and CLAUDE.md compliance它的目标Objective是对最近变更的文件执行一次彻底的技术审查重点检查bug、安全问题以及对Archon 项目已文档化约定的遵守情况。它不是泛泛的代码风格评审而是面向提交前质量关卡的工程实践——与仓库根目录下 CLAUDE.md项目约定入口和 AGENTS.md编码智能体守则共同构成 Archon 的质量保障体系。在 Archon 的实际开发流程中这个命令与同目录下的配套命令协同工作.claude/commands/validation/code-review-fix.md消费审查报告并修复问题修复后运行bun run validate全量校验.claude/agents/code-reviewer.md实现仅报告高置信度问题80 分以上的审查代理.claude/commands/validation/validate-2.md端到端验证脚本其 Phase 1 就包含type-check、lint、format:check等基础关卡。流程第 1 步收集代码库上下文审查不能凭空进行第一步是读取项目约定明确应当遵守的标准读取 CLAUDE.md 获取项目级约定。仓库中的 CLAUDE.md 本身只是入口Agent rules: read AGENTS.md真正的规范主体在 AGENTS.md 中包括产品边界、工程品味、Git 与工作区安全、测试与验证、Pull Request 规则等读取任何相关的.claude/rules/文件获取领域特定模式。需要说明的是从当前仓库源码结构看.claude/rules/目录尚未实际存在对应领域规则分散在 AGENTS.md 各章节中命令文档预留了这一扩展点若日后添加领域规则文件即可在此被引用。流程第 2 步识别待审查的变更命令给出了明确的 git 操作序列用于划定审查范围git status git diff HEAD git diff --stat HEAD以及检查新增的未跟踪文件git ls-files --others --exclude-standard关键要求是每个新文件要完整阅读每个被修改的文件要完整阅读而不是只看 diff——只有读完整个文件才能理解完整上下文避免因为不了解周边逻辑而误判。这与 AGENTS.md 中的原则一致Treat the source, its call sites, and its tests as the current evidence把源码、调用点和测试当作当前证据。流程第 3 步六类审查维度详解命令为每个变更或新增文件定义了六类检查维度以下结合仓库源码逐类展开。3.1 逻辑错误Logic Errors差一错误off-by-one、不正确的条件判断缺失错误处理或静默失败竞态条件尤其 async/streaming 代码不正确的 TypeScript 类型收窄。静默失败在 Archon 中被明确视为红线——AGENTS.md 要求 Fail clearly永远不要静默吞掉错误或扩大权限。在 Agent 运行时环境中静默回退可能浪费资金或扩大能力范围。3.2 安全问题Security Issues原生查询中的 SQL 注入渲染内容中的 XSS暴露的密钥或 API Key不安全的数据处理。命令要求将安全问题标记为CRITICAL。仓库在 packages/core/src/utils/credential-sanitizer.ts 中提供了凭据清理工具有配套测试 credential-sanitizer.test.tsAGENTS.md 同时规定绝不记录凭据、密钥值、用户消息内容或不必要的个人数据。3.3 性能问题Performance ProblemsN1 数据库查询缺少清理事件监听器、定时器、AbortControllerReact 组件中不必要的重渲染无界数组增长。命令特别强调 Missing cleanup这与 AGENTS.md 中关于资源生命周期的要求呼应进程不得在没有明确所有者区分的情况下标记未终止的工作为失败定时器仅适用于可恢复操作重试退避、子进程超时、已终止数据的清理。3.4 类型安全Type Safety无正当理由使用any函数缺少类型注解不正确的类型断言as强转在存在窄类型的地方使用过宽类型。AGENTS.md 对此有专门章节 Let types carry invariants保持 TypeScript strict当健全类型足以表达状态时避免any和宽泛断言用可辨识联合类型discriminated unions和构造函数让非法状态难以表达保持接口窄化。3.5 Archon 特定约定Archon-Specific Conventions这是命令文档中最具项目特色的部分每一条都能在源码或测试中找到对应证据Import 模式类型专用导入用import type禁止import * as core。例如 packages/git/src/branch.ts 中的import { execFileAsync } from ./exec、packages/paths/src/logger.ts 中的import type { Logger } from pino即为规范用法。git 操作使用execFileAsync而非exec全仓库 git 操作统一走 packages/git/src/exec.ts 封装的execFileAsync如 packages/git/src/branch.ts 中的 checkout、commit、status 等操作均通过execFileAsync(git, [...])执行。绝不执行git clean -fdAGENTS.md 的 Git and workspace safety 章节明确禁止破坏性清理命令要求保留用户变更包括未跟踪文件。结构化 Pino 日志事件命名{domain}.{action}_{state}日志层在 packages/paths/src/logger.ts 中基于 pino 实现import pino from pinoTTY 且非生产环境时使用pino-pretty作为目标流。从仓库根目录运行bun run test而非bun test这与 AGENTS.md 的解释一致——Buns module mocks pollute the process cache. Use the package test scripts that preserve isolation; do not runbun testfrom the repository root。根目录 package.json 中test: bun run scripts/repo-tests.ts而mock.module()隔离机制在 packages/core/src/config/config-loader.test.ts 等大量测试中使用冲突 mock 需拆分为独立测试批次。ESLint 零警告策略根目录 package.json 中lint: bun run scripts/check-test-cleanup-drift.ts bun run scripts/lint.ts而validate脚本中明确追加--max-warnings 0。3.6 包边界合规Package Boundary Compliance包之间不得存在循环依赖archon/git和archon/paths不得从archon/core导入archon/workflows通过窄接口注入依赖而非直接导入 core。这些约束与 AGENTS.md 的 Architecture and ownership 章节一致Workflow execution depends on injected contracts, not on core database or adapter implementations并由根目录脚本check:cli-import-boundaryscripts/check-cli-import-boundary.ts在 CI 层面机器化执行。流程第 4 步确认问题是真实存在的命令要求在使用报告前先验证每个问题通过检查实际 TypeScript 定义来确认类型错误结合上下文验证安全问题确保被标记的模式确实是违规而非误报仅报告高置信度问题80——不标记风格偏好或既有问题。这与 .claude/agents/code-reviewer.md 中的评分体系完全对齐0-79 分直接丢弃80-89 报告为 Important90-100 报告为 Critical。核心哲学是Precision over recall——漏掉次要问题优于制造误报。流程第 5 步输出结构化审查报告审查结果保存到.agents/code-reviews/[descriptive-name].md。报告包含两部分变更统计StatsFiles Modified: X Files Added: X New lines: X Deleted lines: -X每个问题的结构化条目severity: critical|high|medium|low file: path/to/file.ts line: 42 issue: [one-line description] detail: [explanation of why this is a problem] suggestion: [how to fix it, with code if helpful] convention: [CLAUDE.md section reference if applicable]如果没有发现问题则输出Code review passed. No technical issues detected.审查输出后修复与验证闭环审查报告并不是终点。配套的 code-review-fix.md 定义了修复流程先完整读取审查文件理解所有问题每个修复需说明错误原因、展示前后对比、创建并运行相关测试验证全部修复完成后运行bun run validate其完整链路由根目录 package.json 定义依次包含 import 边界检查、bundled 产物一致性检查、类型检查、零警告 lint、格式检查、安装测试与全量测试。总结审查的黄金原则回顾整个命令Important 一节浓缩了这套审查方法论的核心Be specific— 给出具体行号而不是模糊抱怨Focus on real bugs— 聚焦真实 bug而非风格偏好Suggest fixes— 给出修复建议而不只是抱怨Flag security issues as CRITICAL— 安全问题一律按 CRITICAL 上报Reference CLAUDE.md conventions— 适用时引用约定出处Do NOT flag pre-existing issues— 不要标记未变更代码中的既有问题。这套流程把代码审查从一次性的主观阅读变成了收集约定 → 划定范围 → 分维度检查 → 验证真实性 → 结构化输出的可重复工程实践配合仓库内 AGENTS.md、CLAUDE.md 与bun run validate校验链构成了 Archon 提交前质量保障的完整闭环。【免费下载链接】ArchonThe first open-source harness builder for AI coding. Make AI coding deterministic and repeatable.项目地址: https://gitcode.com/GitHub_Trending/archon3/Archon创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考