本文档作为 AI agent 的长期记忆和协作参考。
本仓库遵循"代码即文档"原则：
| 文档 | 职责 | 原则 |
|---|---|---|
| 代码本身 | 具体实现逻辑 | 自解释，通过测试验证 |
docs/internal.md |
架构文档 | 极度精简，只记 high-level |
docs/dev/behaviors.md |
可观测行为契约 | 能观测到的行为 |
docs/dev/todo.md |
已知问题 & 待办 | Bug 分析、改进计划、上游依赖 |
AGENTS.md |
对 agent 的指导性原则 | 思维模式、决策框架 |
契约优先：系统演进基于 docs/dev/behaviors.md 定义的行为契约
观测性：关注可观测行为（API 响应、状态转换、UI 变化），而非实现细节
演化性：小步改进，持续优化；不必等到完美重构
行为是契约；测试是验证。
测试应聚焦于外部可观测行为，优先用最快的确定性层验证：
- 纯逻辑 → Unit
- API 契约 → Integration
- 用户旅程 → E2E
设计可测试性：当行为只能通过慢/脆弱路径测试时，考虑重构设计（引入 seams、提取纯逻辑、使异步流程可等待）
确定性优于时序：优先用显式就绪信号和可等待完成，而非固定等待
当你感到犹豫或不适时，就是信号：
• "我不确定改这个会影响哪里" → 耦合度高，考虑解耦 • "测试这个真麻烦" → 可测试性差，考虑引入 seams • "这个文件怎么越来越大" → 职责模糊，考虑拆分 • "为什么要这样设计？" → 缺少上下文，考虑注释或重构
• 契约变化（系统行为/验证方法）：API/状态/UI行为 → docs/dev/behaviors.md
• 经验积累（思维模式/原则陷阱）：发现新模式/避坑指南 → AGENTS.md
• 架构演进：技术决策、架构概述 → docs/internal.md
• 发现脱节：文档与代码不一致 → 同步或说明原因
• 已知问题/待办：Bug 分析、改进计划、上游依赖 → docs/dev/todo.md
关键原则：当信息能帮助未来agent减少认知负担时，就应该记录。
查看 git log --oneline -20 了解最近的修改和决策历史。Git commit message应该清楚说明"为什么"做出某个改变。
好的文档应该：
- ✅ 减少认知负担（读后更清晰，而非更困惑）
- ✅ 提供决策框架（告诉"如何判断"，而非"做什么"）
- ✅ 启发主动思考（留有解释空间，而非穷尽场景）
如果文档让你感到：
- "这部分好冗长" → 考虑简化或拆分
- "找不到重点" → 考虑增加结构或标题
- "不确定是否适用" → 考虑增加原则性指导
- "文档碎片化，多处重复" → 考虑规整到一处，需要的地方改为索引
- 版本迁移：当前无需考虑（软件未发布），直接做正确的设计
- 技术债：优先做正确的事，避免为小改动妥协
- 错误处理：生产代码禁止使用
unwrap()，优先用?传播错误；expect()仅限"程序无法继续"的初始化场景；unwrap_or*系列允许使用 - 提交前：运行相关测试集（backend/frontend/全量）
- 代码提交：所有对 origin/main 的修改，必须通过 merge PR 的方式进行
- Git 工作流：
- 禁止跳过 hooks：绝不使用
git commit/push --no-verify，这会绕过 pre-commit 和 pre-push hooks（代码格式化、测试运行、lint 检查），导致不合规代码进入仓库 - 必须等待测试通过：pre-push hooks 会运行完整测试套件，必须等待测试全部通过后再推送到远程
- 禁止跳过 hooks：绝不使用