351 lines
11 KiB
Markdown
351 lines
11 KiB
Markdown
# AI-Native Software Engineering Standard (AI-NSES)
|
||
|
||
| 项 | 内容 |
|
||
| --- | --- |
|
||
| Version | 0.2 |
|
||
| Scope | 可复用软件工程标准 |
|
||
| Audience | 人类开发者、产品人员、架构师、AI Agent |
|
||
|
||
## 1. Purpose
|
||
|
||
AI-NSES 是一套面向 AI 协作开发的软件工程标准。
|
||
|
||
它不属于某一个具体项目，而是描述：
|
||
|
||
- 项目应该如何组织。
|
||
- 文档应该如何维护。
|
||
- AI Agent 应该如何工作。
|
||
- 开发流程应该如何闭环。
|
||
|
||
目标是让任何新的 AI Agent 在几分钟内理解项目，而不依赖历史聊天记录。
|
||
|
||
## 2. Design Philosophy
|
||
|
||
### Documentation First
|
||
|
||
复杂软件首先是知识，其次才是代码。代码是项目知识的一种实现形式。
|
||
|
||
### Context Driven
|
||
|
||
Prompt 是临时的，Context 是长期资产。重要知识应该沉淀在仓库，而不是沉淀在聊天记录里。
|
||
|
||
### Living Documentation
|
||
|
||
文档不是一次性产物。文档随着项目成长，开发结束时文档也应该同步结束。
|
||
|
||
### AI as Team Member
|
||
|
||
AI 不是单纯的代码生成器，而是项目成员。它可以参与需求分析、产品设计、架构设计、开发、Review 和维护。
|
||
|
||
## 3. Core Principle
|
||
|
||
Build a project that teaches AI.
|
||
|
||
Do not teach AI every day.
|
||
|
||
中文说明：让项目成为 AI 的长期记忆，而不是每次都重新解释项目。
|
||
|
||
## 4. Recommended Project Structure
|
||
|
||
```text
|
||
project/
|
||
├── AGENTS.md
|
||
├── CONTEXT.md
|
||
├── PROJECT_STATE.md
|
||
├── docs/
|
||
│ ├── domain/
|
||
│ ├── architecture/
|
||
│ ├── workflows/
|
||
│ ├── adr/
|
||
│ ├── specs/
|
||
│ └── guidelines/
|
||
├── src/
|
||
└── tests/
|
||
```
|
||
|
||
中文说明：实际项目可以使用 `client/`、`server/`、`backend/`、`frontend/` 等目录，只要在 `CONTEXT.md` 或项目架构文档中说明映射关系即可。
|
||
|
||
## 5. Document Responsibilities
|
||
|
||
### AGENTS.md
|
||
|
||
读者：所有 AI Agent。
|
||
|
||
职责：规定 Agent 如何工作，包括默认工作流程、Debug 原则、Spec 原则、文档更新原则和 Review 原则。
|
||
|
||
更新频率：极低。
|
||
|
||
### CONTEXT.md
|
||
|
||
读者：人类成员和 AI Agent。
|
||
|
||
职责：介绍项目整体背景，包括产品目标、技术栈、系统组成、当前模块和当前开发方向。
|
||
|
||
更新频率：低。
|
||
|
||
### PROJECT_STATE.md
|
||
|
||
读者：人类成员和 AI Agent。
|
||
|
||
职责：记录当前项目状态，包括当前 Sprint、当前 Feature、当前 Priority、Known Issues 和 Next Steps。
|
||
|
||
更新频率：高。建议每完成一个 Feature 或 Checkpoint 更新一次。
|
||
|
||
### docs/domain/
|
||
|
||
读者：产品、业务、开发和 AI Agent。
|
||
|
||
职责：记录业务知识。建议一个业务对象一个文档，例如 `Guest.md`、`Hotel.md`、`Order.md`、`Reservation.md`、`Email.md`、`Task.md`、`PMS.md`。
|
||
|
||
内容包括定义、生命周期、业务规则和关系。禁止记录实现细节。
|
||
|
||
更新频率：低。
|
||
|
||
### docs/architecture/
|
||
|
||
读者：架构、开发和 AI Agent。
|
||
|
||
职责：记录系统设计，例如 `ARCHITECTURE.md`、`DATABASE.md`、`EVENTS.md`、`MODULES.md`。
|
||
|
||
重点描述模块边界、系统通信、数据库、事件和部署边界。
|
||
|
||
更新频率：低。
|
||
|
||
### docs/workflows/
|
||
|
||
读者：产品、业务、开发和 AI Agent。
|
||
|
||
职责：记录业务流程，例如 Email Processing、Reservation Sync、Task Generation、Webhook Processing。
|
||
|
||
重点描述输入、输出、状态流转、异常和补偿。
|
||
|
||
更新频率：中。
|
||
|
||
### docs/adr/
|
||
|
||
读者：架构、开发和 AI Agent。
|
||
|
||
职责：记录重要架构决策。每个重要设计决策一份文档。
|
||
|
||
建议格式：背景、为什么、备选方案、最终选择、影响。
|
||
|
||
规则：ADR 永远追加，不覆盖历史。
|
||
|
||
### docs/specs/
|
||
|
||
读者：产品、开发、测试和 AI Agent。
|
||
|
||
职责：记录具体功能规格。每一个 Feature 对应一个 Spec。
|
||
|
||
生命周期：Draft -> Approved -> Implemented -> Superseded / Archived。
|
||
|
||
规则：Spec 完成以后保留，不删除。
|
||
|
||
如果既有项目已经有 `docs/project/requirements/` 等历史目录，可以通过项目级 adoption 文档建立映射；但新增重要 Feature 仍应使用 Spec 模板的结构表达背景、目标、非目标、业务规则、接口或交互契约、验收标准和测试范围。
|
||
|
||
### docs/guidelines/
|
||
|
||
读者：开发、测试和 AI Agent。
|
||
|
||
职责：记录长期规范，例如 API、UI、CODING、TESTING、SECURITY。
|
||
|
||
更新频率：极低。
|
||
|
||
## 6. Knowledge Layers
|
||
|
||
### Long-term Knowledge
|
||
|
||
生命周期：整个项目。
|
||
|
||
包括 Vision、Domain、Architecture、Guidelines。
|
||
|
||
### Medium-term Knowledge
|
||
|
||
生命周期：一个版本或一个阶段。
|
||
|
||
包括 Workflow、ADR、Spec。
|
||
|
||
### Short-term Knowledge
|
||
|
||
生命周期：一个 Sprint 或一个开发周期。
|
||
|
||
包括 Current Sprint、Known Issues、Next Steps、Backlog。
|
||
|
||
## 7. Stable vs Dynamic Documents
|
||
|
||
长期稳定：
|
||
|
||
- `AGENTS.md`
|
||
- `CONTEXT.md`
|
||
- `docs/domain/`
|
||
- `docs/architecture/`
|
||
- `docs/guidelines/`
|
||
|
||
中期演进：
|
||
|
||
- `docs/workflows/`
|
||
- `docs/adr/`
|
||
- `docs/specs/`
|
||
|
||
高频更新：
|
||
|
||
- `PROJECT_STATE.md`
|
||
|
||
中文说明：这样可以避免整个仓库每天发生无意义变化，也能让新 Agent 快速判断哪些文档代表长期事实，哪些文档代表当前状态。
|
||
|
||
## 8. Feature Lifecycle
|
||
|
||
任何 Feature 默认按以下顺序推进：
|
||
|
||
```text
|
||
Idea
|
||
-> Requirement
|
||
-> Discussion
|
||
-> Specification
|
||
-> Implementation
|
||
-> Verification
|
||
-> Documentation Update
|
||
-> Done
|
||
```
|
||
|
||
Documentation Update 属于 Definition of Done，不能跳过。
|
||
|
||
### 8.1 Definition of Ready
|
||
|
||
进入实现前，复杂 Feature 或会影响跨模块协作的变更必须满足：
|
||
|
||
- 需求来源明确，知道是谁提出、解决什么问题。
|
||
- 目标和非目标明确，避免实现时扩大范围。
|
||
- 受影响的用户、业务流程、接口、数据模型、权限、安全、审计或外部系统边界已经列出。
|
||
- 前端、后端、测试或第三方系统的分工已经明确。
|
||
- 验收标准已经可测试，至少有主要 Given / When / Then 场景。
|
||
- 未确认问题已经列出；如果问题影响业务规则或安全边界，应先确认再实现。
|
||
|
||
简单 bugfix 或纯内部重构可以不用新建完整 Spec，但仍应在任务说明中写清目标、范围和验证方式。
|
||
|
||
### 8.2 Definition of Done
|
||
|
||
Feature 完成前必须确认：
|
||
|
||
- 实现满足本次 Spec、Change Request 或任务说明。
|
||
- 相关自动化测试、类型检查、lint、构建或手工验证已经运行，或明确说明无法运行的原因。
|
||
- 受影响的需求、Spec、Workflow、Domain、ADR、接口契约、安全边界和 Project State 已同步。
|
||
- 对外或跨团队契约发生变化时，调用方文档和测试说明已同步。
|
||
- 没有把 Secret、真实客户数据、构建产物、临时文件或无关本地变更纳入交付。
|
||
|
||
### 8.3 Change Request
|
||
|
||
当一个已 Approved 或 Implemented 的 Spec 发生需求变更时，优先新增或更新 Change Request，而不是把讨论散落到聊天记录中。
|
||
|
||
Change Request 至少说明：
|
||
|
||
- 变更背景。
|
||
- 原规则。
|
||
- 新规则。
|
||
- 影响范围。
|
||
- 迁移或兼容策略。
|
||
- 前端、后端、测试和文档待办。
|
||
- 验收标准。
|
||
|
||
小变更可以直接追加到原 Spec 的“变更记录”章节；跨前后端、权限、安全、数据模型或第三方契约的变更应单独成文。
|
||
|
||
### 8.4 Traceability Matrix
|
||
|
||
复杂 Feature 应维护需求追踪表，用于连接需求、实现、测试和文档。
|
||
|
||
推荐字段：
|
||
|
||
| 需求项 | 后端状态 | 前端状态 | 测试状态 | 文档位置 | 当前状态 |
|
||
| --- | --- | --- | --- | --- | --- |
|
||
| 示例需求 | Pending / Done / N/A | Pending / Done / N/A | Pending / Done / Blocked | Spec / Contract / README | Draft / Approved / Implemented |
|
||
|
||
追踪表可以放在 Spec、Project State 或专项 checkpoint 文档中；关键是让新 Agent 能快速判断“文档写了但代码没做、代码做了但文档没写、后端做了但前端没做、前端需要但后端没做”。
|
||
|
||
### 8.5 Agent Handoff
|
||
|
||
给 AI Agent 分派任务时，建议使用统一交接结构：
|
||
|
||
- 背景：为什么做。
|
||
- 目标：本次必须完成什么。
|
||
- 边界：本次不做什么。
|
||
- 必读文档：从入口文档到具体 Spec / Contract。
|
||
- 影响范围：后端、前端、测试、第三方、数据、权限、安全、审计。
|
||
- 验收标准：可执行或可观察的检查项。
|
||
- 允许写操作：是否允许改代码、改文档、造数据、点确认按钮或清理测试数据。
|
||
- 输出要求：代码位置、测试结果、文档更新清单、风险和下一步建议。
|
||
|
||
## 9. AI Working Principles
|
||
|
||
- AI 应先理解，再开发。
|
||
- 复杂需求默认先讨论，不立即编码。
|
||
- 复杂功能默认先 Spec，不直接实现。
|
||
- Bug 默认先定位，不猜测修复。
|
||
- UI 默认保持一致性，不过度设计。
|
||
- 代码修改前先确认目标、边界和验收标准。
|
||
- 涉及接口、安全、权限、数据模型或外部系统时，先读相关契约文档。
|
||
- 涉及跨 agent 协作时，先确认 Spec、Change Request 或 handoff 是否足够清楚。
|
||
|
||
## 10. Documentation Rules
|
||
|
||
所有文档必须回答一个问题：
|
||
|
||
未来的新 Agent 为什么需要阅读它？
|
||
|
||
如果回答不了，就不要创建，也不要维护。
|
||
|
||
文档应该小、独立、易维护。
|
||
|
||
不要维护一个 8000 行的 `DOMAIN.md`。应该按对象拆分成 `Order.md`、`Guest.md`、`Hotel.md`、`Email.md`、`Task.md`。
|
||
|
||
通用标准只规定文档职责和流程。具体项目可以新增 Project Overlay，记录本项目专属的需求门禁、核心概念、交付格式和安全边界；Overlay 不应反向污染通用标准。
|
||
|
||
## 11. Documentation Update Rules
|
||
|
||
完成 Feature 后必须检查：
|
||
|
||
- Domain 是否需要更新。
|
||
- Architecture 是否需要更新。
|
||
- Workflow 是否需要更新。
|
||
- ADR 是否需要新增。
|
||
- Spec 是否需要改为 Implemented 或补充结果。
|
||
- Project State 是否需要更新。
|
||
- 安全、权限、接口契约是否需要同步。
|
||
- Traceability Matrix 是否需要更新。
|
||
- Change Request 是否需要关闭、合并到 Spec 或标记为 Superseded。
|
||
|
||
如果没有文档变化，应明确说明：
|
||
|
||
```text
|
||
No documentation changes required.
|
||
```
|
||
|
||
不要为了修改而修改文档。
|
||
|
||
## 12. Success Criteria
|
||
|
||
一个新的 AI Agent 进入项目后，阅读以下有限文档即可开始工作：
|
||
|
||
```text
|
||
AGENTS.md
|
||
-> CONTEXT.md
|
||
-> PROJECT_STATE.md
|
||
-> 项目级 Overlay 或 Adoption 文档
|
||
-> 相关 Domain
|
||
-> 相关 Workflow
|
||
-> 相关 Spec 或 ADR
|
||
```
|
||
|
||
无需阅读整个代码库。
|
||
|
||
无需依赖历史聊天记录。
|
||
|
||
## 13. Scope
|
||
|
||
AI-NSES 不限制编程语言、框架、数据库或 AI 模型。
|
||
|
||
它适用于 Codex、Claude Code、Gemini CLI、Cursor，以及未来任何 AI Agent。
|
||
|
||
它描述的是软件工程，不是某个具体工具。
|
||
|
||
具体项目如果有更强的安全、合规、业务流程或多 agent 协作要求，应通过项目级 Overlay 补充，不直接把项目私有业务规则写入本通用标准。
|