# AI-Native Software Engineering Standard (AI-NSES)

| 项 | 内容 |
| --- | --- |
| Version | 0.1 |
| 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 -> Archived。

规则：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，不能跳过。

## 9. AI Working Principles

- AI 应先理解，再开发。
- 复杂需求默认先讨论，不立即编码。
- 复杂功能默认先 Spec，不直接实现。
- Bug 默认先定位，不猜测修复。
- UI 默认保持一致性，不过度设计。
- 代码修改前先确认目标、边界和验收标准。
- 涉及接口、安全、权限、数据模型或外部系统时，先读相关契约文档。

## 10. Documentation Rules

所有文档必须回答一个问题：

未来的新 Agent 为什么需要阅读它？

如果回答不了，就不要创建，也不要维护。

文档应该小、独立、易维护。

不要维护一个 8000 行的 `DOMAIN.md`。应该按对象拆分成 `Order.md`、`Guest.md`、`Hotel.md`、`Email.md`、`Task.md`。

## 11. Documentation Update Rules

完成 Feature 后必须检查：

- Domain 是否需要更新。
- Architecture 是否需要更新。
- Workflow 是否需要更新。
- ADR 是否需要新增。
- Spec 是否需要改为 Implemented 或补充结果。
- Project State 是否需要更新。
- 安全、权限、接口契约是否需要同步。

如果没有文档变化，应明确说明：

```text
No documentation changes required.
```

不要为了修改而修改文档。

## 12. Success Criteria

一个新的 AI Agent 进入项目后，阅读以下有限文档即可开始工作：

```text
AGENTS.md
-> CONTEXT.md
-> PROJECT_STATE.md
-> 相关 Domain
-> 相关 Workflow
-> 相关 Spec 或 ADR
```

无需阅读整个代码库。

无需依赖历史聊天记录。

## 13. Scope

AI-NSES 不限制编程语言、框架、数据库或 AI 模型。

它适用于 Codex、Claude Code、Gemini CLI、Cursor，以及未来任何 AI Agent。

它描述的是软件工程，不是某个具体工具。