— AI Agent 上下文 > 本文件遵循 [AGENTS.md 开放规范](https://agents.md/)，供 Claude Code、Qwen Code、Cursor、Copilot 等 AI 工具读取。 > 由炼境接入包分发。请按项目实际补全下方 TODO 段落。 ## 项目概况 ## 核心开发约束 ### 包管理 - **pnpm 唯一**：禁止 npm / yarn / npx / bun - lock 文件只有 `pnpm-lock.yaml`，不生成其他 ### 代码规范 - TypeScript 优先，避免 `any` - 函数/变量 camelCase；组件 PascalCase - 异步统一 `async/await`，不用裸 Promise 链 - 错误处理明确 `try/catch`，不吞异常 - 优先编辑现有文件，避免创建不必要的新文件 ## Git 工作流 见 `docs/ai-context/git-workflow.md`（分支策略 + Conventional Commits + PR 规范）。 **commit 必须符合 Conventional Commits**（lefthook 强制），炼境据此采集飞轮数据。 ## 架构与模块 ## 多 AI CLI 协作 本项目可由多个 AI CLI 协同。交接时把结果总结成 3 条传给下一个： ``` 1. 已完成：<改了哪些文件 + 核心决策> 2. 待验证：<需要确认的地方> 3. 约束继承：<影响后续的关键限制> ``` ## 关键文档索引 --- ## Agent 友好工程四支柱 修改代码前，确认这个项目满足四支柱： **可导航**：凭文件名/目录名可在 30 秒内定位某功能的代码。通用能力有独立家，不寄生在业务模块下。 **可推理**：公共类型只在一处定义。改一个接口，类型检查能报出所有受影响处。 **可验证**：typecheck / lint / test 各有一条命令真能跑。关键路径有冒烟测试。 **可记忆**：规则按场景注入（不是一份巨型文档）。决策只写"为什么"，代码自己回答"是什么"。 --- ## 文档防腐元规则 做任何改动时，判断它属于哪类变更： ### T1 外部契约变更（最高优先级） 其他代码、服务、或 agent 依赖的定义——接口、共享类型、数据结构、配置键名、环境变量名。 → 查 `docs/ai-context/project-context.yaml`（若存在）找到记录该契约的文档，检查并同步更新。 ### T2 架构边界变更 模块划分、目录结构、依赖方向、包边界调整。 → 检查架构文档是否需要同步。 ### T3 工具链变更 引入或替换库、框架、构建工具。 → 更新本文件（AGENTS.md）技术栈声明；通知炼境重新扫描并更新 `project-context.yaml`。 ### T4 常驻上下文过期 本文件（AGENTS.md）或 `docs/ai-context/project-brief.md` 描述的现实已经改变。 → 立即更新。这两份文档常驻 agent 上下文，过期危害最大。 ### 不触发检查 内部重构、性能优化、bug fix（外部行为不变）、测试文件、临时脚本。 --- ## 文档防腐铁律 - 文档只写稳定的：为什么、铁律、意图、架构决策。 - 易变的（端口、路由、表名、命令清单）交给工具自省，不写死进常驻文档。写死 = 定时炸弹。 - 单一事实来源：两处说同一事时，删掉派生的那处。 - 两份文档打架时，信代码，不信文档。 --- ## 定期防腐自查 每隔一阵或大改后，对照以下清单： - [ ] AGENTS.md 里的技术栈声明还和代码一致吗？ - [ ] `docs/ai-context/project-brief.md` 最近 30 天有没有随架构改动更新？ - [ ] 有没有两份文档说同一件事且打架？ - [ ] `docs/ai-context/project-context.yaml` 的契约路径还准确吗？