MindOS AGENTS.md

Agent 协作规则

所有 Coding Agent（Claude Code、Cursor、Windsurf、Cline 等）在本项目中必须遵守的规则。 流程编排见 Slash Commands（.claude-internal/commands/），本文件只定义标准和模板。

代码规范

• 单文件尽量不要超过 1000 行；确有必要超过时必须有明确拆分理由和后续拆分计划；源码、测试、脚本和文档文件一定不能超过 3000 行（生成物、lockfile、自动生成快照除外）。

Spec 模板

每个 spec 文件（wiki/specs/spec-*.md）必须包含以下段落，不能留空：

# Spec: <标题>

## 目标
一句话说清楚要解决什么问题、达到什么效果。

## 现状分析
当前的行为/架构是什么，为什么不满足需求。

## 数据流 / 状态流
用文字或 ASCII 图描述改动涉及的数据流转路径。
重点标注：哪些组件读数据、哪些组件写数据、中间经过几层缓存。
（这一段是 self-review 时最重要的锚点——sidebar 不更新的 bug 就是因为缺这个分析）

## 方案
具体怎么做。包含技术选型和关键设计决策。

## 影响范围
- 变更文件列表
- 受影响的其他模块（即使不改它，也要说明为什么不受影响）
- 是否有破坏性变更

## 边界 case 与风险
列出至少 3 个边界 case 和对应处理方式。
列出已知风险和 mitigation。

## 验收标准
可执行的 checklist，每条都能客观判断 pass/fail。

测试规范（每个改动必须遵守）

测试先行

• 新功能：先写测试（红灯）→ 再写实现（绿灯）→ 再重构
• Bug fix：先写能复现 bug 的测试 → 再修复 → 确认测试变绿
• 重构：先确认现有测试通过 → 重构 → 确认测试仍然通过

三类 case 必须覆盖

类型	说明	示例
正常路径	典型输入，预期输出	创建文件成功、API 返回 200
边界 case	极端/临界输入	空字符串、超长路径、并发调用、Unicode 文件名、磁盘满
错误路径	非法输入、外部失败	文件不存在、网络断开、权限不足、JSON 格式错误

边界 case 发现清单

写测试时逐条过：

• 空值：null / undefined / 空字符串 / 空数组 / 空对象
• 类型边界：0 / -1 / MAX_SAFE_INTEGER / NaN / Infinity
• 字符串边界：含空格 / 特殊字符 / Unicode / emoji / 超长（>1000字符）
• 集合边界：空集合 / 单元素 / 重复元素 / 超大集合
• 时序边界：并发调用 / 重复提交 / 超时 / 中途取消
• 环境边界：文件不存在 / 目录不存在 / 权限不足 / 磁盘满
• 状态边界：首次运行 / 已有数据迁移 / 降级模式

测试质量自检

• 测试名是否描述了行为而非实现？（'returns 404 for missing file' 而非 'test case 3'）
• 测试是否独立？（不依赖其他测试的执行顺序或副作用）
• 测试是否快速？（单个测试 <100ms，全量 <30s）
• 测试是否明确？（失败时能直接看出哪里错了）

测试目录分层

测试按“归属边界”放置，不追求单一目录：

• packages/<domain>/<pkg>/src/*.test.ts：package 内部单元测试，靠近源码；多模块 package 用行为/模块名，只有单模块或 public entrypoint contract 才用 index.test.ts
• packages/web/__tests__/、packages/desktop/src/*.test.ts、packages/mobile/__tests__/：App 专属组件、运行时和业务逻辑测试
• tests/*.test.ts：repo 级 contract（迁移、发布包、workflow、legacy cleanup）
• tests/unit/*.test.ts：根 CLI、packaging、跨 package 的纯单元测试
• tests/integration/*.test.ts 与 tests/e2e/*.spec.ts：真实服务/端口/浏览器测试，手动运行，不进入默认 pnpm test
• .next/、_standalone/、.turbo/ 中的测试文件是生成物/缓存，不作为源码测试入口