85 lines
4.2 KiB
Markdown
85 lines
4.2 KiB
Markdown
# 本项目 AI-NSES 落地说明
|
||
|
||
## 1. 目标
|
||
|
||
本文说明 TH Hotel Simple 如何采用 AI-Native Software Engineering Standard (AI-NSES)。
|
||
|
||
本次落地只建立文档标准化入口，不搬迁现有历史文档，不删除已有文档，不改变代码结构。
|
||
|
||
## 2. 当前采用方式
|
||
|
||
AI-NSES 推荐目录和本项目当前目录的映射如下：
|
||
|
||
| AI-NSES 角色 | 本项目当前位置 | 中文说明 |
|
||
| --- | --- | --- |
|
||
| Agent 工作规则 | `AGENTS.md` | 当前项目协作、开发、安全、分支和测试规则。 |
|
||
| 项目长期上下文 | `CONTEXT.md` | 产品目标、系统组成、技术栈、业务领域和外部系统边界。 |
|
||
| 项目当前状态 | `PROJECT_STATE.md` | 当前 checkpoint、优先级、已确认事实、Known Issues 和 Next Steps。 |
|
||
| 项目文档索引 | `docs/project/README.md` | 当前项目专属文档总索引和权威来源说明。 |
|
||
| 项目级 Overlay | `docs/project/ai-nses-project-overlay.md` | 当前项目在 AI-NSES 之上的需求门禁、核心概念守门、V4 文档和 agent 交接规则。 |
|
||
| 通用规范 | `docs/import/reusable/` | 可复制到后续项目的通用标准、开发规范和模板。 |
|
||
| 当前项目需求 / Spec | `docs/project/requirements/` | 当前阶段仍沿用既有目录保存功能需求和方案。 |
|
||
| 当前项目集成契约 | `docs/project/integrations/` | SuperAgent、AgentBus 和 MCP 对接资料。 |
|
||
| 当前项目安全边界 | `docs/project/security-access-control-boundary.md` | 接口暴露、权限、酒店隔离和审计边界总表。 |
|
||
| 当前项目前后端协作 | `docs/project/frontend-backend/` | 前后端字段、接口和调试页面协作入口。 |
|
||
|
||
## 3. 暂不搬迁的原因
|
||
|
||
当前项目已经有大量历史需求、集成契约、前后端协作文档和导入资料。
|
||
|
||
如果一次性把这些文档搬到 `docs/domain/`、`docs/architecture/`、`docs/workflows/`、`docs/specs/`，会带来以下风险：
|
||
|
||
- 历史链接失效。
|
||
- 当前开发基线不容易判断。
|
||
- 大量文件移动会干扰代码 Review。
|
||
- 新 Agent 反而需要同时理解旧路径和新路径。
|
||
|
||
因此当前阶段采用“入口标准化 + 索引映射”的方式。
|
||
|
||
## 4. 后续演进原则
|
||
|
||
- 新增重要 Feature 时，优先形成独立 Spec；涉及 V4 业务卡、SuperAgent 入站、前后端接口、权限、安全、审计或普通用户页面时，必须按 `docs/project/ai-nses-project-overlay.md` 先形成或更新 Spec / Change Request。
|
||
- 新增重要架构决策时，新增 ADR，不覆盖历史。
|
||
- 新增稳定业务概念时，再补 Domain 文档。
|
||
- 新增跨模块流程时，再补 Workflow 文档。
|
||
- 后端、前端、测试或文档 agent 的任务交接，应使用 AI-NSES handoff 结构，并补充本项目 overlay 要求的影响范围和输出要求。
|
||
- 只有当迁移能降低理解成本时，才考虑移动旧文档。
|
||
- `PROJECT_STATE.md` 是唯一允许高频更新的顶层项目状态文档。
|
||
|
||
## 5. Agent 默认阅读顺序
|
||
|
||
新的 Agent 进入项目后，默认先读：
|
||
|
||
1. `AGENTS.md`
|
||
2. `CONTEXT.md`
|
||
3. `PROJECT_STATE.md`
|
||
4. `README.md`
|
||
5. `docs/project/README.md`
|
||
6. `docs/project/ai-nses-project-overlay.md`
|
||
7. 当前任务相关的需求、集成、安全或前后端协作文档
|
||
|
||
涉及接口、权限、审计、酒店隔离或敏感数据返回时，必须阅读 `docs/project/security-access-control-boundary.md`。
|
||
|
||
## 6. Feature Definition of Done
|
||
|
||
功能完成前需要确认：
|
||
|
||
- 代码或文档是否满足本次验收标准。
|
||
- 对应测试或基础检查是否运行。
|
||
- `PROJECT_STATE.md` 是否需要更新。
|
||
- 需求、Spec、Workflow、ADR 或集成契约是否需要更新。
|
||
- 安全、权限、酒店隔离和审计边界是否受影响。
|
||
- 如果是 V4 需求，需求追踪表是否已更新，是否符合项目级 overlay 的核心概念守门和 agent 交接规则。
|
||
|
||
如果没有文档变化，应在交付说明中明确：
|
||
|
||
```text
|
||
No documentation changes required.
|
||
```
|
||
|
||
## 7. 给后续 Agent 的一句话
|
||
|
||
本项目的长期记忆应优先来自仓库文档，而不是历史聊天记录。
|
||
|
||
遇到聊天记录和仓库文档不一致时，先以 `AGENTS.md`、`CONTEXT.md`、`PROJECT_STATE.md` 和 `docs/project/README.md` 中的当前有效文档为准；如果仍有冲突，再向用户确认。
|