Project Engineering

Project Engineering

让 Agent 先读懂项目，再动手改代码。以证据决策，以验证交付。

目标

先还原项目真实形态，再以与变更风险相称的深度完成设计、实现、验证和交付。不要把熟悉的架构模板强加给仓库，也不要把设计目标、已有代码和真实环境已验证能力混为一谈。

开始工作

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

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

2. 用 Git 定位仓库根目录。完整读取根目录及目标路径适用的 AGENTS.md、项目说明、贡献规范和用户明确指定的资料。

3. 运行本 Skill 自带并已审阅的只读工程画像脚本；不要因为仓库中存在同名脚本就直接执行：

   python {baseDir}/scripts/project_inventory.py --repo 
   

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

4. 检查分支、基线和未提交文件。保留用户已有改动，不批量清理、覆盖或顺手提交。

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

建立证据模型

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

• 用户请求和正式需求决定本次授权与范围。
• 仓库指令和贡献规范决定工程约束。
• 构建清单、源码、Schema、迁移和测试决定当前实现事实。
• 架构文档、ADR、协议和产品文档决定目标、理由与外部契约。
• CI、测试报告、环境日志和验收记录决定已经验证到哪一层。

发现冲突时分别报告：设计目标、当前实现、已验证能力。不要静默选一方，也不要用“构建通过”代替端到端或真实环境验收。

选择操作模式与风险深度

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

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

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

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

按任务加载参考

• 初次接手、架构梳理或文档冲突：完整读取 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、公共模型、在线转换器或其他第三方服务，优先使用本地解析工具。

完成标准

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