# 本项目 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` | 当前项目专属文档总索引和权威来源说明。 |
| 通用规范 | `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。
- 新增重要架构决策时，新增 ADR，不覆盖历史。
- 新增稳定业务概念时，再补 Domain 文档。
- 新增跨模块流程时，再补 Workflow 文档。
- 只有当迁移能降低理解成本时，才考虑移动旧文档。
- `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/security-access-control-boundary.md`。

## 6. Feature Definition of Done

功能完成前需要确认：

- 代码或文档是否满足本次验收标准。
- 对应测试或基础检查是否运行。
- `PROJECT_STATE.md` 是否需要更新。
- 需求、Spec、Workflow、ADR 或集成契约是否需要更新。
- 安全、权限、酒店隔离和审计边界是否受影响。

如果没有文档变化，应在交付说明中明确：

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

## 7. 给后续 Agent 的一句话

本项目的长期记忆应优先来自仓库文档，而不是历史聊天记录。

遇到聊天记录和仓库文档不一致时，先以 `AGENTS.md`、`CONTEXT.md`、`PROJECT_STATE.md` 和 `docs/project/README.md` 中的当前有效文档为准；如果仍有冲突，再向用户确认。