Agentic Development：面向 Codex 的智能代码审查与重构工作流系统

一套基于 Codex 的智能化开发工作流系统，支持代码库分析、功能建模、切片审查、并行波浪式重构以及显式合并控制，为大型代码库的渐进式改进提供结构化解决方案。

• 原作者/维护者：sunpar
• 来源平台：github
• 原始标题：agentic_development
• 原始链接：https://github.com/sunpar/agentic_development
• 来源发布时间/更新时间：2026-05-30T13:15:48Z

原作者与来源

• 原作者/维护者：sunpar
• 来源平台：github
• 原始标题：agentic_development
• 原始链接：https://github.com/sunpar/agentic_development
• 来源发布时间/更新时间：2026-05-30T13:15:48Z 原作者与来源\n\n- 原作者/维护者: sunpar\n- 来源平台: GitHub\n- 原始标题: agentic_development\n- 原始链接: https://github.com/sunpar/agentic_development\n- 发布时间: 2026-05-30\n\n---\n\n项目概述\n\nAgentic Development 是一套面向 Codex（OpenAI 的 AI 编程助手）的智能化开发工作流系统。它将传统的人工代码审查流程转化为结构化、可自动化的 AI 驱动工作流，支持从代码库分析到功能建模、从切片规划到并行重构的完整开发周期。该系统特别适用于需要对大型代码库进行渐进式改进的场景，通过将大任务拆分为可独立执行的"切片"（Slices），实现高效的并行化处理。\n\n---\n\n核心功能模块\n\n代码库分析与功能建模\n\n系统首先对目标代码库进行全面的库存分析（Inventory），识别代码结构、入口点、测试覆盖情况等关键信息。基于分析结果，构建功能模型（Feature Model），该模型包含：\n\n- 代码路径与模块依赖关系\n- 测试用例分布与覆盖情况\n- 已知风险与未知区域标识\n- 文档与实现的一致性检查\n\n功能模型作为后续所有操作的基础，确保 AI 对代码库有结构化的理解，而非仅基于文本片段进行猜测。\n\n审查切片规划\n\n根据功能模型，系统自动生成审查切片计划（Slice Plan）。每个切片代表一个独立的、可并行执行的改进任务，例如：\n\n- 特定模块的重构\n- 某一类问题的批量修复\n- 文档同步更新\n- 测试用例补充\n\n切片之间相互独立，可以安全地并行执行，大幅缩短整体开发周期。\n\n波浪式并行编排\n\n系统采用"波浪"（Wave）的概念管理切片执行。每个波浪可以配置：\n\n- 最大并行度: 控制同时运行的切片数量\n- 允许的操作类型: PR 创建、审查请求、合并操作\n- 合并策略: 支持 --no-merge（仅生成）、--allow-merge（自动合并）、--merge-method squash（压缩合并）\n\n这种设计允许用户从 dry-run 模式开始验证，逐步过渡到全自动化执行。\n\n---\n\n系统架构与目录结构\n\n项目采用模块化设计，主要包含以下组件：\n\nagentic-dev-system 模块\n\n负责构建/任务规划、任务工作流管理、PR 辅助工具、测试与修复、文档生成以及技能发现。该模块是系统的"大脑"，协调各个子系统的运作。\n\ncodebase-review-system 模块\n\n专注于功能建模、审查切片生成、波浪编排、合并门控、测试验证、模式定义、提示工程以及技能管理。该模块处理与代码直接相关的智能分析任务。\n\nconfigs 目录\n\n提供可选的全局 Codex 配置模板，包括代理 TOML 文件、钩子配置、AGENTS.md 和 hooks.json，支持备份机制确保配置安全。\n\nscripts 目录\n\n包含安装脚本和端到端的审查/重构包装脚本，简化系统的部署和日常使用。\n\n---\n\n安全默认与风险控制\n\n系统在设计时将安全性放在首位：\n\n- 合并默认禁用: 除非显式提供 --allow-merge，否则不会执行任何合并操作\n- PR-only 模式: --pr-only 或 --no-merge 始终优先于合并权限\n- 外部工作目录: 默认在 ~/.codex/runs/codebase-review 运行，不直接修改目标仓库\n- 配置备份: 安装前自动备份现有的 Codex 配置文件\n- 全局配置可选: 不强制安装全局配置，用户可按需选择\n\n这些设计确保即使在自动化工作流中，用户也能保持对代码库的完全控制。\n\n---\n\n典型工作流程\n\n安装与初始化\n\nbash\n克隆仓库并安装\npython3 scripts/install.py --dry-run 先验证\npython3 scripts/install.py 正式安装\n\n可选：安装全局配置\npython3 scripts/install.py --install-global-config\n\n\n生成并运行审查切片\n\nbash\n1. 生成代码库库存\npython3 ~/.codex/codebase-review-factory/scripts/detect_repo_inventory.py \\\n --output docs/agentic-system/repo-inventory.json\n\n2. 构建功能模型\npython3 ~/.codex/codebase-review-factory/scripts/build_feature_model.py \\\n docs/agentic-system/repo-inventory.json \\\n --output docs/agentic-system/feature-model.json\n\n3. 请求 Codex 优化功能模型\n提示词：使用 codebase-deep-analyzer 和 feature-model-builder...\n\n4. 验证功能模型\npython3 ~/.codex/codebase-review-factory/scripts/validate_feature_model.py \\\n docs/agentic-system/feature-model.json\n\n5. 生成切片计划\npython3 ~/.codex/codebase-review-factory/scripts/generate_slice_plan.py \\\n docs/agentic-system/feature-model.json \\\n --output-dir docs/agentic-system/review\n\n6. 验证切片计划\npython3 ~/.codex/codebase-review-factory/scripts/validate_slice_plan.py \\\n docs/agentic-system/review/slice-plan.json\n\n\n波浪式执行\n\nbash\n仅 dry-run 验证\npython3 ~/.codex/codebase-review-factory/scripts/orchestrate_slice_waves.py \\\n docs/agentic-system/review/slice-plan.json \\\n docs/agentic-system/review/slice-plan.json \\\n --dry-run \\\n --max-parallel 999 \\\n --allow-pr \\\n --allow-review-request \\\n --allow-merge \\\n --merge-method squash\n\n正式执行（仅 PR，不合并）\npython3 ~/.codex/codebase-review-factory/scripts/orchestrate_slice_waves.py \\\n docs/agentic-system/review/slice-plan.json \\\n docs/agentic-system/review/slice-plan.json \\\n --max-parallel 999 \\\n --allow-pr \\\n --allow-review-request \\\n --no-merge\n\n完整执行（包含合并）\npython3 ~/.codex/codebase-review-factory/scripts/orchestrate_slice_waves.py \\\n docs/agentic-system/review/slice-plan.json \\\n docs/agentic-system/review/slice-plan.json \\\n --max-parallel 999 \\\n --allow-pr \\\n --allow-review-request \\\n --allow-merge \\\n --merge-method squash\n\n\n中断恢复\n\nbash\npython3 ~/.codex/codebase-review-factory/scripts/orchestrate_slice_waves.py \\\n docs/agentic-system/review/slice-plan.json \\\n docs/agentic-system/review/slice-plan.json \\\n --run-dir \"/path/to/original/run-dir\" \\\n --worktree-dir ~/.codex/worktrees/codebase-review \\\n --resume \\\n --reuse-worktrees \\\n --max-parallel 999 \\\n --allow-pr \\\n --allow-review-request \\\n --allow-merge \\\n --merge-method squash\n\n\n---\n\n技术特点与创新点\n\n结构化 AI 协作\n\n不同于简单的"让 AI 改代码"，该系统建立了人与 AI 之间的结构化协作框架。通过功能模型、切片计划等中间产物，人类开发者可以审查 AI 的理解是否正确，在关键节点进行干预，而非完全黑盒式地依赖 AI 输出。\n\n渐进式自动化\n\n从 dry-run 到 PR-only 再到完整合并，系统支持逐步提升自动化程度。这种设计让团队可以先在小范围验证工作流的有效性，再推广到生产环境。\n\n并行化与可恢复性\n\n波浪式执行模型天然支持并行化，同时通过工作目录隔离和状态持久化，支持任意时刻的中断和恢复。这对于可能需要数小时甚至数天才能完成的大型重构任务至关重要。\n\n---\n\n应用场景\n\n- 遗留代码现代化: 逐步将老旧代码库迁移至新框架或新语言版本\n- 技术债务清理: 批量处理代码异味、重复代码、测试缺失等问题\n- 大规模重构: 在保持功能不变的前提下优化架构\n- 文档同步: 确保代码注释、README 与实际实现保持一致\n- 合规性改造: 为满足新的安全或规范要求进行批量修改\n\n---\n\n总结与展望\n\nAgentic Development 代表了 AI 辅助软件开发的一个重要演进方向：从简单的代码补全和问答，转向结构化的、可管控的自动化工作流。通过将 AI 的能力封装在明确的流程和边界内，该系统既发挥了 AI 的处理速度和规模优势，又保留了人类开发者的决策权和质量把控能力。随着 Codex 等 AI 编程助手的不断成熟，类似的工作流系统将成为大型软件项目管理的标准工具。\n\n---\n\n关键词: Codex, AI编程助手, 代码审查, 自动化重构, 工作流编排, 并行处理, 代码库分析, 功能建模, 渐进式改进