工程开发标准
这份标准不是面向小团队的轻量开发手册，而是专为 AI 参与实现、文档、验证和交接的人机协作工程工作流设计。它帮助人类负责人和 AI 编码代理共享可靠上下文、明确任务与权限边界、产出可验证的变更，并保留可追溯的决策。设计依据是工程职责和风险，不是团队人数；适用于个人维护者、多人组织以及一个或多个 AI 代理参与的产品、服务、应用、SDK、静态网站、工具和研究型项目。它不要求每项任务都使用 AI，也不绑定特定厂商或工具。课程作业默认不纳入个人项目组合标准，用户明确要求时按该项任务的范围执行。
标准是共同默认值，不要求所有项目采用同一种架构或工具。项目可以有多个 GitHub 仓库和多个 GitHub Projects；Docker、数据库、微服务、独立文档站和复杂 CI 都由项目实际需要决定。人类负责人对需求、授权、评审与交付负责；AI 在明确范围内执行，并如实提供验证证据。
如何使用
- 使用 AI 参与开发工作流 约定人类责任、任务契约、操作权限和完成证据。
- 在 项目生命周期 确认当前要解决的问题、范围、风险和验收方式。
- 对跨仓库项目，先建立 项目、仓库与看板关系图；不要先移动源码。
- 按项目职责和复杂度挑选 文件结构 与 文档组合，从 模板库 复制有用的部分。
- 在 本地开发与 Docker 写明人类和 AI 都能复现的开发模式、命令、端口、配置和数据生命周期。
- 交付前使用 测试、安全与可访问性 中与风险相称的检查，并记录实际验证结果。
规则等级
| 等级 | 使用方式 |
|---|---|
| 必须 | 对当前项目职责必需的底线，例如保留用户数据、明确配置来源、如实报告验证。 |
| 推荐默认 | 没有更好的现有约定时采用；有合理原因时记录偏差即可。 |
| 条件适用 | 由真实特性触发，例如公开 API、持久化数据、多租户、付费操作、线上服务或外部发布。 |
| 不适用 | 写出具体原因；不要为了完整而新建空目录或空文档。 |
| 采用差距 | 规则适用但还未满足；写明风险、最小下一步和验证方式。 |
每个适用的重要约定应能找到负责维护的人或标记为待定、唯一权威位置、验证方法，以及已接受的兼容性例外。规则设计本身不代表 GitHub 分支保护、CI、备份或线上监控已经配置。
按项目类型裁剪
| 类型 | 基线 | 需要时再增加 |
|---|---|---|
| 小型应用、CLI、静态站 | 用途、运行命令、目录、配置、有效验证和版本身份 | Docker、持久化数据、部署、可访问性细节 |
| 线上服务 | 小型项目基线，加接口与数据责任、本地复现、权限、安全、发布与运维 | 消息队列、多租户、容量目标、恢复目标 |
| 多仓库平台 | 跨仓库关系、组件责任、契约、隔离开发环境和集成验收 | 共享基础设施、跨服务恢复和协调发布 |
| SDK 或库 | 公开接口、兼容承诺、使用示例、包发布和消费者验证 | 多运行时矩阵、生成代码、签名与来源证明 |
| 研究、数据或 AI | 来源与许可、实验配置、随机种子、评估方法、环境和结果证据 | GPU、模型服务、数据或论文发布 |
这份标准的权威性
本站是工程约定的导航和可读视图。每个实际项目仍由自己的代码、锁文件、迁移、接口定义、配置和运维文档说明当前事实。项目的权威文档入口应链接这里适用的规范，并标出本项目的差异；不要把本站的计划误当成已经实施的事实。