在共享工作树中开发跨平台 CLI，且不破坏他人的工作

## 只在当前工作树内搜索和修改 采用工作树开发时，当前工作目录就是活动分支的完整仓库。搜索、读取、构建、测试和编辑都只能在该根目录内进行。 - 使用相对路径，或已解析到当前根目录下的路径。 - 不要假定父目录就是仓库。 - 不要到同级工作树中搜索实现或配置。 - 拒绝硬编码的开发者主目录路径。 - 从活动根目录解析夹具和源文件路径。 离开工作树可能会把其他分支的陈旧代码混入分析和变更。 ## 不重置或删除其他会话的改动 应假定陌生文件和编辑可能属于另一个活动会话。绝不能仅因某项工作不在当前任务范围内，就将其删除、重置、丢弃或覆盖。 - 保留并非由你创建的文件。 - 移除未跟踪文件前先征求确认。 - 未经明确批准，不得执行重置、签出丢弃、清理或删除暂存工作等操作。 - 如果钩子因你未触碰的文件而失败，应报告冲突，而不是修改这些文件。 - 将变更限制在请求范围内，并检查最终差异。 将共享工作树状态视为用户数据；执行破坏性操作前，必须先明确其所有权。 ## 通过注册表添加命令，不到处加条件分支 使用注册表使命令、提供程序和集成具备扩展性。新实现应满足稳定接口，并通过唯一的规范路径注册，而不是在整个应用程序中增加条件分支。 - 为主要行为定义接口。 - 通过构造函数或字段注入依赖项。 - 使用仓库支持的生成器生成模拟对象。 - 对带默认值的可扩展配置采用函数式选项。 - 每个职责明确的文件只保留一个命令实现。 - 新增专用软件包，而不是扩充通用工具软件包。 引入平行逻辑前，先搜索现有命令层、执行层和软件包层。 ## 上下文只用于取消和期限，标志统一经过一个解析器 请求上下文只能用于取消、截止时间和少量请求范围值。函数接受上下文时，应将其置于首个参数。不要用上下文隐藏配置、依赖项或普通参数。 将配置建模为确定性流水线： 1. 加载配置源； 2. 处理导入和继承； 3. 按命令标志、环境、文件、默认值的顺序应用优先级； 4. 渲染受支持的模板； 5. 生成有效配置。 通过统一解析器处理标志和环境绑定。新增选项时更新所有归属该选项的架构，绝不能绕过中央绑定层。 ## 把可管道传递的数据和面向人的信息写到不同的输出流 可通过管道传递的结果只能写入数据流。提示、进度、警告和格式化的人类可读消息应写入界面流。结构化日志仅用于系统事件，不用于面向用户的输出。 - 使用共享I/O抽象，而不是直接打印。 - 由UI层负责颜色、图标、Markdown、终端宽度和能力检测。 - 当终端不支持样式或在持续集成环境中运行时，自动降级显示。 - 禁用人类可读格式后，仍要保持结构化数据有效。 - 始终应用机密信息屏蔽，且不要在遥测中采集用户数据。 测试或录制标志可以强制指定终端特性，但生产默认值应继续感知实际环境。 ## 保持函数精简，并用稳定的分类包装错误 保持文件和函数职责集中。从高复杂度编排中提取具名步骤，使顶层函数呈现为平坦的流水线。 - 使用仓库规定的格式、导入分组、别名和注释标点。 - 保留有帮助的注释，并在行为变化时同步更新。 - 对有实质意义的公开操作应用标准性能跟踪。 - 在策略允许时，简单访问器、构造函数、纯查询和简单委托可以例外。 - 使用稳定类别包装错误，并保留根因。 - 合并相互独立的失败时，不要丢失任一错误链。 - 通过语义匹配而不是字符串比较检查已包装的错误。 当用户需要提示、上下文或退出语义时，使用信息充分的错误构建器。 ## 用模拟对象和真正可能失败的测试来检验行为 对隔离行为优先采用使用生成模拟对象的快速单元测试；当公开命令行为跨越真实边界时，再增加集成或验收覆盖。 - 使用表驱动用例覆盖输入和错误。 - 测试行为，而不是内部实现。 - 移除桩函数、同义反复式测试以及永久跳过的测试。 - 对合并后的集合，分别修改结果和源，并通过独立检查证明双向隔离。 - 对切片结果，除长度外还要断言有代表性的内容。 - 增加负向测试，证明缺少触发条件时恢复逻辑不会启动。 - 对已包装的失败使用语义错误匹配。 只有当断言确实可能因受保护行为出错而失败时，覆盖率才构成证据。 ## 编写在各平台都能运行、准备缺失时明确失败的测试 测试必须能在受支持的桌面和服务器平台上运行，不得假定存在某种外壳、路径分隔符或平台专用工具。 - 使用标准路径库，从独立组成部分构建路径。 - 仅在进行可移植的后缀比较或显示时规范化分隔符。 - 使用测试可执行文件或注入的运行器，而不是平台专用命令。 - 将子进程门控合并到现有测试入口，不要再定义重复入口。 - 遍历或计数前，将夹具根目录解析为绝对路径。 - 当前提条件或夹具计数配置缺失时，让防护检查明确失败。 - 对字段重命名后必须使测试失败的架构字段，增加编译期哨兵。 测试依赖子进程行为前，先通过明确的前提子测试验证隐式环境传播。 ## 用测试工具重新生成快照，而不是手动编辑 黄金快照包含不可见格式、终端宽度、样式以及受环境影响的输出。绝不能手工编辑。 - 通过受支持的测试标志或生成器重新生成快照。 - 接受变更前检查生成的差异。 - 不要将快照或终端测试接入管道，因为重定向可能改变能力检测。 - 命令帮助或输出变化时，一并重新生成相关录制内容。 - 验证录制内容中不存在命令失败、引用缺失或机器专用路径泄漏。 - 未明确列入范围时，不要更改受保护的夹具或测试数据。 生成输出必须通过其归属源文件和规范工作流来更改。 ## 为每个新命令写文档，并把推迟的工作登记为议题 每个新命令、标志、参数或配置表面都需要用户文档，其中应包含仓库要求的元数据、用法、示例、参数、标志和视觉证据。 - 核实已声明的页面标识符，不要根据文件名猜测URL。 - 变更后构建文档站点，并检查链接、图像和组件。 - 仅在命令行为、帮助或输出变化时重新生成视觉捕获；纯文字编辑无需执行。 - 按指定位置和命名约定放置需求文档。 - 延后工作时，应在合并前创建可跟踪的问题，并链接其标识符。 - 使发布说明、路线图数据和标签与变更类别保持一致。 承诺了未跟踪后续工作的文档并不完整。 ## 不跳过钩子、不用破坏性 Git 命令来更新评审 使用仓库规定的评审工作流；除非已明确授权持久服务，否则应将重复维护自动化限定在当前会话内。 - 仅通过获准的分支流程执行变基或更新。 - 检查持续集成，并处理尚未解决的评审线程。 - 在原评审线程内回复，并验证关联关系。 - 更新评审前，运行补丁范围内的lint和测试覆盖率检查。 - 不要绕过钩子，也不要使用跳过验证的标志。 - 不要提交草稿笔记、研究材料或未解决的占位内容。 在明确确认会丢失哪些内容之前，绝不能执行破坏性Git命令，也不能移除其他会话的工作。 ## 先写重现 bug 的测试，并从根源修复未通过的检查 修复缺陷时，先编写复现测试并观察其失败，再实现最小修复并检查回归。 完成前确认： - 项目可使用固定工具链完成编译； - 已更改文件通过规范格式化器和lint检查； - 快速测试通过，并在受影响路径需要时运行完整测试或验收测试； - 覆盖率达到强制阈值，且没有流于形式的断言； - 生成的模拟对象、架构、快照、文档和视觉捕获均为最新； - 复杂度和文件大小仍满足限制； - 跨平台路径和子进程测试具备可移植性； - 差异中没有机密信息、用户数据或无关工作。 修复每个失败门控的根因，而不是削弱门控。