4.2 KiB
4.2 KiB
本项目 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 进入项目后，默认先读：
AGENTS.mdCONTEXT.mdPROJECT_STATE.mdREADME.mddocs/project/README.mddocs/project/ai-nses-project-overlay.md- 当前任务相关的需求、集成、安全或前后端协作文档
涉及接口、权限、审计、酒店隔离或敏感数据返回时，必须阅读 docs/project/security-access-control-boundary.md。
6. Feature Definition of Done
功能完成前需要确认：
- 代码或文档是否满足本次验收标准。
- 对应测试或基础检查是否运行。
PROJECT_STATE.md是否需要更新。- 需求、Spec、Workflow、ADR 或集成契约是否需要更新。
- 安全、权限、酒店隔离和审计边界是否受影响。
- 如果是 V4 需求，需求追踪表是否已更新，是否符合项目级 overlay 的核心概念守门和 agent 交接规则。
如果没有文档变化，应在交付说明中明确：
No documentation changes required.
7. 给后续 Agent 的一句话
本项目的长期记忆应优先来自仓库文档，而不是历史聊天记录。
遇到聊天记录和仓库文档不一致时，先以 AGENTS.md、CONTEXT.md、PROJECT_STATE.md 和 docs/project/README.md 中的当前有效文档为准；如果仍有冲突，再向用户确认。