AI 协作
MuseMVP 的 AI 协作体系：内置规则、AI 友好目录与文档/手册分工。
MuseMVP 将 AI 协作视为工程基础设施。除了内置 AGENTS.md、.agents 等规则与技能入口，目录分层本身也针对 AI 可理解性做了设计。本页聚焦长期稳定的协作框架；高频迭代的技巧与工具前沿，统一沉淀在 MVP 手册。
先看分工：文档 vs MVP 手册
开发文档（/docs）
沉淀稳定知识：架构边界、目录规范、分层职责、提交前核查。适合作为团队共识与 onboarding 基线。
MVP 手册（/manual）
追踪高时效内容：最新 AI IDE 用法、Prompt 策略、模型能力变化、实战踩坑与修复。
建议搭配阅读
本页负责“长期不变的协作框架”，而 AI IDE 实时使用总结 负责“持续变化的战术细节”。
MuseMVP 内置的 AI 协作基础设施
AGENTS.md：定义必须遵循的工程约束，减少 AI 输出偏离项目规范。.agents/skills：把高频开发场景模块化，支持按需触发与复用。src/modules + backend分层：让 AI 更容易判断“编排逻辑”和“数据访问”应放在哪里。
规则文件不要写成百科
规则应短小、可执行、可验证。过长的规则文件会降低关键约束的命中率。
为什么这套目录对 AI 更友好
按业务域聚合
`src/modules/*` 将组件、hooks、lib 共置，AI 更容易在同一上下文完成实现与重构。
后端强分层
`routes -> modules/lib(orchestrator) -> queries` 责任清晰，减少跨层误改。
类型安全链路
Hono RPC + TypeScript 在编译阶段暴露前后端不匹配问题。
i18n 有固定落点
用户文案集中在 `src/i18n/translations/*/mvp.json`，便于 AI 同步中英文。
推荐 AI 协作流程（稳定版）
先给上下文，不要直接让 AI 开写
指明目标文件、影响模块、是否涉及鉴权/计费/i18n。
先让 AI 输出改动计划
计划至少包含文件路径、分层改动点、验证命令。
按分层实施
建议顺序：queries -> modules/lib -> routes -> api-client -> UI。
要求 AI 自检
至少完成类型检查与构建检查，并报告失败点。
人工做最终把关
重点检查权限边界、计费链路、翻译同步与错误分支。
Context:
- Feature: src/modules/muse-billing
- Route: src/backend/api/routes/upgrade
- Query: src/backend/database/queries/billing-contracts.ts
- i18n: src/i18n/translations/{en,zh}/mvp.json
Task:
新增“降级到免费版”接口与前端操作按钮。
要求：
1) 严格遵循 modules/lib 编排 + queries 数据访问分层
2) 用户可见文案同步更新 en/zh 的 mvp.json
3) 完成后运行 pnpm type-check && pnpm build提交前核查（PR 前必做）
| 检查项 | 要求 |
|---|---|
| 类型正确性 | pnpm type-check 通过 |
| 构建可用性 | pnpm build 通过 |
| 代码规范 | pnpm check 无错误 |
| 分层边界 | 是否遵循 queries -> modules/lib -> routes -> api-client -> UI |
| i18n 同步 | 用户可见文案是否同步更新中英文 |
pnpm type-check
pnpm build
pnpm check把验证命令写进提示词
让 AI 在提交前自执行验证，是降低返工率最有效的做法之一。
实时技巧与前沿工具：请看 MVP 手册
/docs 负责沉淀稳定方法论；当你需要“本周可用”的 AI coding 战术（新模型对比、最新 Agent 工具链、Prompt 新范式、实战踩坑修复），请直接查看 MVP 手册。