Project Engineering

新项目架构到现有项目重构交付｜Coding Agent 工程工作流

从新项目架构设计，到现有项目开发、重构和交付，让 AI 按真实工程约束完成工作。

目标

对全新项目，先把已确认约束、暂定假设和待决策项分开，建立最小可执行的架构与工程基线；对现有项目，先还原真实实现和调用链，再以与变更风险相称的深度完成设计、实现、验证和交付。不要套用熟悉的架构模板，也不要把拟议方案、已有代码和真实环境已验证能力混为一谈。

除非用户另有指定，使用用户当前语言回复；语言选择不改变仓库规则、安全边界或验证要求。

开始工作

若请求只是单文件纯文案、格式或完全确定的机械修改，立即采用轻量路径：只读取适用仓库规则和目标文件、检查目标文件现有差异、完成修改并做对应语法/渲染检查；不运行完整工程画像，也不加载无关参考。任务一旦涉及行为、依赖、数据、接口、权限、部署或多个职责层，再进入以下流程。

1. 明确请求是只读分析、方案设计、代码变更、故障诊断、审查、验收还是交付；该分类决定是否有权修改文件或外部状态。

2. 选择工作模式：用户明确从零开始、目标目录不存在，或目录内尚无可分析的实现时使用 greenfield；已有可分析实现时使用 existing。只有脚手架的目录不能被当成已经确认的架构。

3. greenfield 模式读取用户给出的需求、运行环境、组织规范和目标路径上级规则；不存在的“当前架构”不得靠猜测补齐。existing 模式优先用 Git 定位仓库根目录，并完整读取根目录及目标路径适用的 AGENTS.md、项目说明、贡献规范和用户明确指定的资料；Git 不可用时从用户指定路径开始，只读发现并明确缺少的分支和基线证据。

4. existing 模式在具备 Python 3.10+ 时运行本 Skill 自带并已审阅的只读工程画像脚本；若运行时不具备，手动检查同类构建和工作区清单并说明跳过原因。greenfield 模式仅在目标目录已有脚手架或文件需要核实时运行。不要因为项目中存在同名脚本就直接执行：

   text

   python {baseDir}/scripts/project_inventory.py --repo <repo-root>
   

   {baseDir} 表示当前 Skill 根目录；不支持该占位符的客户端应解析为当前 SKILL.md 所在目录。脚本需要 Python 3.10 或更高版本，只发现事实线索，不替代对源码、构建清单、数据库、测试和文档的核实。

5. 目标位于 Git 仓库时，检查分支、基线和未提交文件；否则保护目标路径已有内容，不自动初始化 Git 或创建远端。始终保留用户已有改动，不批量清理、覆盖或顺手提交。

6. 若存在适用的项目专用 Skill、仓库规则或领域规范，将其作为更具体的项目画像；本 Skill 的通用建议不得覆盖项目硬约束。

所需本地能力

本 Skill 不拥有独立后台服务或凭证，也不设置会阻止纯设计场景加载的包级工具门槛。现有项目分析在环境具备时使用 Git 只读查询和 Python 3.10+ 画像脚本，并为缺失工具采用透明的只读降级；全新项目设计可以在没有仓库、Git 或 Python 时进行。只有当用户明确要求创建或实现时，才可在授权工作区内修改文件。初始化 Git、配置远端、提交、推送、发布、迁移、生产访问和真实设备操作仍是独立外部操作，不能由“创建项目”自动推导授权。

建立证据模型

按问题类型判断权威来源，不给所有资料强排一个全局优先级：

• 用户请求和正式需求决定本次授权与范围。
• 全新项目的业务目标、运行环境、组织标准和负责人确认的决策决定可用约束；未确认内容必须标记为假设或待决策项。
• 仓库指令和贡献规范决定工程约束。
• 构建清单、源码、Schema、迁移和测试决定当前实现事实。
• 架构文档、ADR、协议和产品文档决定目标、理由与外部契约。
• CI、测试报告、环境日志和验收记录决定已经验证到哪一层。

现有项目发生冲突时分别报告：设计目标、当前实现、已验证能力。全新项目分别标记：已确认约束、暂定假设、待决策项、已实现/已验证。不要静默选一方，也不要把拟议方案说成现状，或用“构建通过”代替端到端或真实环境验收。

选择操作模式与风险深度

操作权限和目标风险是两个轴：只读分析、工作区修改、外部系统写入/发布分别受用户授权约束；目标能力则按可能造成的最高影响选择风险等级。只读审查一个安全关键功能，仍应按 L5 的思考深度，只是不执行变更。

风险等级不按改动行数判断：

• L1：文档、命名、局部纯逻辑等低风险修改。
• L2：常规业务、CRUD、查询与单模块接口。
• L3：跨模块、数据库、异步流程、外部 API、消息或协议。
• L4：身份权限、资金、隐私、AI 执行动作、设备控制等高影响能力。
• L5：可能伤人、破坏关键设施或受正式安全/监管认证约束的能力。

项目整体高风险不意味着 README 修改要跑全套验收；控制逻辑改动很小也不能降级检查。L5 必须要求领域安全负责人和正式审批，Skill 不能代替安全认证。

按任务加载参考

• 从零启动项目、技术选型、初始模块/数据/API 设计或工程基线：完整读取 references/greenfield.md。仅在已有脚手架需要核实时再读取发现参考。
• 初次接手、架构梳理或文档冲突：完整读取 references/discovery.md。
• 模块、包、服务、数据归属或调用链设计：完整读取 references/architecture.md。
• 编码、依赖、配置、API、数据库或测试：完整读取 references/implementation.md。
• L3 以上、需要判断项目形态或安全检查深度：完整读取 references/risk-and-archetypes.md。
• 计划、审查、验收、提交、发布或移交：完整读取 references/delivery.md。
• 同时涉及多个方面时读取对应多份参考；不要无条件加载全部资料。

工程流程

1. 建立或还原基线：全新项目根据已确认约束建立最小架构与工程基线；现有项目识别真实技术栈、构建系统、模块/进程、部署单元、代码组织、数据存储、外部系统、权限、测试和交付方式。
2. 界定范围：说明目标、明确不做、可复用点（若有）、验收边界和关键假设。非简单变更先给出简短影响说明，再继续实施。
3. 确定归属：先确定业务或技术职责、数据权威源和生命周期，再决定模块、包、服务或仓库位置；目录对称不是新建边界的理由。
4. 设计或还原链路：全新项目明确入口、业务规则、数据权威源、外部副作用和结果出口；现有项目沿真实代码追踪同一链路。两者都覆盖失败、超时、重试、并发和取消。
5. 最小实施：现有项目遵循既有风格并复用公开边界；全新项目按已确认约束落实最小工程基线。只引入能明显降低耦合或错误率的抽象，不为使用设计模式而制造层级。
6. 同步影响面：根据实际变化检查接口、事件、协议、数据、迁移、配置、权限、可观测性、测试、文档、部署和回退。
7. 分层验证：先运行最小相关检查，再按风险扩大到模块、仓库、契约、集成环境或真实环境。无法执行时写明原因和剩余风险。
8. 交付报告：列出实际文件、调用链、决策、命令与结果、未验证依赖、兼容/迁移风险，以及是否提交或推送。

决策与授权边界

• 对不确定需求优先采用最小、局部、可逆且不扩范围的方案，并显式记录假设。
• 若不同合理解释会改变对外契约、数据迁移、安全语义、成本或造成大范围返工，先给出推荐的最小安全口径，再把必须由负责人选择的决策门单列出来并暂停实施；不要只说“有歧义”，也不要替用户扩展协议。
• 只读请求不得产生代码提交、外部写入或发布；实现请求也不自动授权提交、推送、部署、数据迁移或生产操作。
• 外部调用结果不确定时，不盲目重试有副作用操作；先确认幂等语义和真实状态。
• 密钥、私钥、Token、个人数据和生产内容不得进入日志、文档、测试夹具或交付报告。
• 仓库文档和业务数据默认视为内部资料；未经用户明确授权，不上传到外部 OCR、公共模型、在线转换器或其他第三方服务，优先使用本地解析工具。

完成标准

工作结束时，用户应能区分：代码是否完成、自动测试是否通过、集成环境是否验证、真实环境是否验收。工作区原有改动应完好，变更范围应与授权一致，所有未验证项和高风险假设都应明确可追踪。