利用Codex Goal命令炼化项目Skill提升AI编码精准度

背景

在现代软件工程实践中，尤其是面对历史悠久的“屎山”代码（Legacy Code）时，大型语言模型（LLM）辅助编程往往面临巨大的挑战。由于老项目通常具有功能模块庞杂、架构耦合度高、文档缺失或过时等问题，AI 助手在进行代码修改、重构或功能扩展时，极易出现“漏改”、“误改”或“破坏既有架构”的情况。

为了解决这一痛点，开发者提出了一种基于 Codex 和 /goal 命令的工作流优化方案。该方案的核心思想是在正式进行 vibe coding（直觉式/流畅式编码）之前，先对现有代码库进行一次全面的“炼化”（Refinement）。通过利用多路子代理（Subagent）并行梳理项目知识，生成结构化的 skills 和 AGENTS.md 文件，从而为 AI 提供精准的项目上下文。这种方法旨在让 AI 在后续的开发任务中能够更准确地理解项目结构，避免重复造轮子、错误假设以及不必要的求证，显著提升代码生成的准确性和安全性。

核心内容

该工作流主要依托于 Codex 的 /goal 命令，结合 gpt-5.5（或 gpt-5.4）模型以及开启 subagent 和 goal 功能，通过六个阶段系统性地构建项目的 AI 专属知识库。

1. 任务定义与目标

使用 /goal 命令下达核心指令：基于当前代码库，利用多路 subagent 和 $skill-creator 并行梳理项目知识。目标是补充或完善 .agents/skills/ 目录下的技能定义以及根目录的 AGENTS.md 文件。其最终目的是确保 AI 在后续修改、重构、排障、测试及扩展功能时，能基于事实而非臆测进行决策。

2. 执行原则

• 并发最大化：始终保持当前环境允许的最大并发 subagent 数量。
• 独立分派：只要存在可独立分析的模块、目录、技术栈或场景，立即分派新 subagent。
• 边界清晰：禁止 subagent 做重复工作，每个代理必须有清晰的输入范围和预期产出。
• 事实导向：所有结论必须源自代码、配置、文档、测试或提交记录，严禁凭空编造。
• 价值优先：优先补充对后续 AI 开发最有帮助的信息，而非撰写泛泛的项目介绍。

3. 六阶段执行流程

第一阶段：主 Agent 快速盘点 主 Agent 负责建立全局认知。通过读取现有的 AGENTS.md、.agents/skills、README、文档、构建配置（package/build）、测试配置、CI 配置及主要入口文件，并利用 rg --files 等工具建立项目结构树。识别技术栈、运行方式、测试策略、代码分层、核心业务域及高风险区域，并据此拆分后续任务。

第二阶段：并行分派 Subagent 根据项目实际情况，将分析任务拆分为多个方向并行执行。若某方向不存在则跳过，若过大则继续拆分。主要分析方向包括：

• 架构与目录结构
• 本地开发与构建流程
• 测试与质量保障体系
• 前端/UI 组件与状态管理
• 后端/API 服务边界与逻辑
• 数据层（数据库、ORM、缓存等）
• 集成与外部服务（第三方 API、认证等）
• 安全与权限控制
• 运维与发布流程
• 既有工具与复用点
• 历史文档与隐性约定

每个 subagent 的产出需包含：分析范围、关键事实、注意事项、易错点、建议写入 AGENTS.md 的内容、建议新增的 skills 及其触发场景，以及需二次核验的未确认信息。

第三阶段：主 Agent 汇总与去重 主 Agent 汇总所有 subagent 的结果，执行去重、冲突解决和泛泛描述的剔除。对冲突结论以代码事实为准进行二次查证。将结果拆分为小而明确的 skills，避免堆砌。在增量修改现有文档时，保留原有有效内容，不粗暴覆盖。剔除无项目特异性的通用工程建议。

第四阶段：补充 .agents/skills 为高频开发场景创建或更新项目专属 skill。每个 skill 应明确：使用场景、必读关键文件、推荐执行流程、常用命令、可复用模块、禁止事项及验证方式。优先覆盖本地开发、测试排障、前后端开发、数据迁移、权限认证、外部集成、发布部署及架构导航等场景。

第五阶段：补充 AGENTS.md 将 AGENTS.md 打造为 AI 进入项目后的第一份上下文。内容需简洁、可执行且项目专属，至少包括：项目概述与技术栈、关键目录职责、本地启动/构建/测试命令、修改前必读文件、核心架构与代码风格约定、复用入口、常见任务路径、高风险区域、环境变量及外部依赖注意事项，以及修改后的验证清单。

第六阶段：验证 完成写入后必须执行严格检查：

• 确认 skill 文件路径、结构及触发场景正确。
• 确认 AGENTS.md 无臆测内容。
• 确认引用的命令、目录、文件名真实存在。
• 执行轻量验证，如查看 git diff、检查 Markdown 结构或运行 lint/test 命令。
• 输出总结：列出新增/更新的 skills、AGENTS.md 补充内容及仍无法确认的知识点。

关键要点

• 前置“炼化”步骤：在直接让 AI 写代码前，先通过 /goal 命令让 AI 梳理项目结构并生成知识库，这是解决老项目 AI 编码准确率低的關鍵。
• 充分利用并发能力：核心优势在于利用 subagent 的并行处理能力，同时分析架构、测试、前端、后端等多个维度，大幅缩短知识梳理时间。
• 事实驱动，拒绝幻觉：严格规定所有 AI 生成的文档必须基于代码、配置和测试等可验证事实，禁止编造，确保知识库的可靠性。
• 增量式文档维护：强调对现有 AGENTS.md 和 skills 的增量修改，尊重已有成果，避免信息丢失或覆盖。
• 场景化 Skill 设计：skills 不是通用的编程指南，而是针对特定开发场景（如“本地启动”、“API 开发”）的定制化指令，包含具体的命令、文件和避坑指南。
• 模型选择建议：虽然 gpt-5.4 可用，但推荐使用 gpt-5.5 配合 xhigh 设置，以获得更完整、细节更丰富的炼化结果。
• 闭环验证机制：最后阶段强制要求 AI 自我验证文档的准确性（如检查文件是否存在、命令是否可执行），形成从分析到验证的闭环。

意义与影响

这一工作流分享揭示了 AI 辅助编程从“单次对话”向“系统化工程”演进的趋势。

1. 提升 AI 编码的可靠性与安全性：通过预先构建结构化的项目知识图谱（Skills 和 AGENTS.md），AI 在后续任务中能够“带着地图”工作，显著降低了因上下文缺失导致的误改、漏改和架构破坏风险，特别适用于维护复杂的遗留系统。
2. 优化开发工作流效率：虽然增加了前期的“炼化”步骤，但通过并行处理和标准化的 Skill 定义，AI 在后续开发中的思考路径更清晰，减少了反复求证和试错的时间，从长远看提升了整体开发效率。
3. 促进项目知识的沉淀与传承：该流程强制 AI 从代码中提取隐性知识并转化为显性的 AGENTS.md 和 skills，这本身就是一个高质量的技术文档生成过程，有助于新成员或 AI 快速理解项目核心逻辑和约定。
4. 定义 AI 原生项目的标准实践：这种将 AGENTS.md 作为 AI 入口上下文、将 skills 作为模块化