# 最佳实践

## 规范

**声明式写，不要叙述式。** 用 `contract:`、`invariant:`、`test:`、`failure:` 这样的章节，不要编号步骤或散文。智能体读得快，跟随精确的声明。

**仅关闭影响实现的决策。** 在移交 `plan` 前，解决：契约、数据形状、失败模式、测试标准。把哲学争论和"锦上添花"留在 `deferred` 或 `Working notes`。

**按路径引用代码，永不粘贴。** 规范是关于要构建什么的决策，不是怎样构建的演走。

## 计划

**任务是 30-60 分钟** 原子化到智能体能推理它们。太大了你失去可见性；太小了失去速度。

**Acceptance 可执行。** 每个任务的验收条件必须是 CI/人类能验证的东西：测试名、命令或脚本。不模糊，不好高骛远。

**标记 `[parallel]` 仅当真正独立。** 共享状态、错误处理或未闭合的契约 → 任务不并行。过度标记导致破坏的合并。

## Git 工作流

**每个 RED-GREEN-refactor 循环一次提交。** 把你的思考推进历史。后来调试时有帮助。

**每个循环后同步文档。** 就在提交前。如果你等待，你会忘记你改了什么和为什么。

**用描述性分支名。** `feat/oauth-github`，不是 `feature1`。当你有多个 worktree 时帮你导航。

## 大型项目

**当 ≥3 个里程碑时用 roadmap。** 不要试着一次性计划他们。`plan` 仅当前的，随着你学习更新 stub。

**清晰标记当前里程碑。** `← 现在详细计划` 在 M1 上信号意图。在计划 M2 前，ship 后移动标记。

**期望在 M1 后修改里程碑。** 第一个里程碑教你剩下的会花费多少。那是要点。

## 调试

**隔离优先，假设其次。** 缩小到最小重现。删除代码直到症状消失。仅然后问"为什么"。

**每次改一个变量。** 并行很诱人但让很难知道哪个改变修复了它。

## 测试

**测试契约，不是实现。** 如果契约说"成功时返回 200"，就测试这。不是"调用 X 函数"或"从数据库 Y 读取"。

**无内部的 mock。** Mock 外部边界：HTTP、DB、文件系统。Mock 你自己的代码仅当真实版本很慢或非确定性。

## 何时放弃

**如果假设实质改变，停止并重新探索。** 不要强行通过如果你在解决的问题不再是问题了。在探索笔记中标记出尝试后得到的原因和经验。

## 规范评审合成 (Spec Review Synthesis)

**评审员建议，Coordinator 裁决。** 规范评审员作为独立 Subagent 按照特定契约运行。主智能体（Coordinator）对审查结果进行批判性评估，解决冲突、补齐遗漏边界，并一次性修补规范，而不是被动堆砌 Subagent 输出。

## 模型分级映射 (Model Tier Mapping)

**根据任务风险匹配模型能力。** 将 `fast` 用于机械化修改或 Lint 检查，`balanced` 用于单组件实现，`strongest` 用于核心协议、安全评审或复杂状态机。在 `.praxis/model-tiers.yaml` 中配置这些分级。

## 多模块协同 (Multi-Module Coordination)

**明确指定一个 Coordinator 仓库。** Coordinator 持有 change-set ID、跨模块规范及工作区计划。严禁在各模块规范中重复定义共享契约；统一引用 Coordinator 规范。提交修改时按依赖顺序执行，Coordinator 仓库最后提交。

## 文档同步

**Living docs 是事实，staging docs 是草稿。** `ship` 后，规范移到 living docs。代码中的测试和注释与两者保持当前。

**README 是第一个规范。** 如果它不匹配代码，PR 失败评审。同样规则适用于所有公共契约。