SkillYard AGENTS.md

SkillYard 实施约束

SkillYard 1.0 优先保证真实用户路径，而不是理论完备性。任何修复如果需要扩大领域模型或生命周期协议，必须首先证明它违反了已承诺的 Product Contract，并证明它能够在正常生产路径中自然发生。否则应记录为 Future Consideration，而不是进入当前实现。 当发现一个新的问题时，默认假设它“不应该修”，而不是默认假设“应该修”。只有在证据足以推翻这个假设时，才允许进入实现。

本文件约束后续在本仓库工作的编码 Agent。产品行为仍以 docs/1.0-product-contract.md 为准，实施顺序以 docs/plans/0001-skillyard-1.0-implementation.md 为准。

单一实现原则

• 1.0 中每项生命周期能力只能有一套 canonical domain model、持久化协议和生产入口。
• 不得自行增加 v2、legacy、next 等并行实现，也不得为了保留本阶段刚写出的代码而维护两套状态机。
• 当前实现不能覆盖已确认需求时，先停止编码，说明“原地重构、替换实现、缩小范围”三种选择及成本；只有用户明确确认后才能改变架构边界。
• 兼容层只能用于已经核验存在的真实用户数据或已发布契约。不能把未发布的开发中间状态推定为兼容要求。

阶段边界

• 只实现当前计划阶段明确列出的行为，不提前建立下一阶段的数据模型、Adapter 或扩展点。
• 开始一个阶段前，先固定该阶段的完整技术实现图，包括唯一领域模型、持久化协议、文件系统生效点、恢复方向、复用能力和文件职责。切片用于验证这张实现图中的不同产品行为，不能用于边写边发现第二套架构。
• 每个切片必须从用户可观察的公开 seam 开始，以一个失败测试进入，以该测试通过结束。
• 一个切片只解决一个产品行为，并独立 commit、push。
• 代码规模只作为审查信号，不是机械停止线。当实现范围明显超出阶段技术图时，必须解释增加的职责，并审查是否出现错误抽象、水平切片或重复能力；不能为了降低行数机械拆文件。
• “功能完整”指计划中的用户主流程和基础能力全部可用，不等于穷尽所有理论边界。新增防御协议前必须说明 1.0 用户如何实际触发该风险及实现成本；同一用户恶意并发、主动追逐私有临时名等低概率对抗场景默认不扩张 1.0。
• 阶段完成后必须完成该阶段验收并报告结果。只有计划明确设置人工确认点、命中架构变更门或缺少外部授权与环境条件时才停止；否则可以继续下一个已批准阶段，但同样要先固定完整技术实现图。

架构变更门

出现以下任一情况时必须停止，并在继续修改前取得用户确认：

• 新增第二套 Plan、Transaction、Journal 或恢复协议；
• 新增带版本后缀的领域类型、表、migration 或模块；
• 为兼容未核验的本地状态而保留旧生产入口；
• 当前阶段需要修改下一阶段的产品边界；
• 测试只能通过调用生产入口不会调用的私有步骤；
• 独立审查发现当前切片无法通过局部修复满足产品契约。

验收纪律

• 主验收测试只通过 SkillYardApplication、typed Tauri command/client、真实临时文件系统和重启后的持久状态观察行为。
• 私有函数测试只能补充算法边界，不能代替真实生产入口测试。
• 提交前检查 diff 范围、相关测试、类型检查和格式；阶段完成时运行全量测试、clippy -D warnings、生产构建和独立代码审查。

测试条件

• 优先使用 tart 在沙箱 VM 中测试。