让同时提供应用和命令行的产品，代码库保持整齐有序

## 先读整体规则文件，再遵守各文件夹自己的规则 将根级指导文件视为跨领域边界、工作流程和命令在整个代码库中的唯一事实来源。 在不重复模块细节的前提下保持简洁，使新贡献者能够据此了解整体情况。 - 发布一个简短索引，指向产品、架构、贡献、评审和当前计划文档。 - 明确标记已归档的规范，绝不把过时决策当作当前行为。 - 为每个主要目录指定自己的指导文件，用于说明局部所有权和约束。 - 在受规则管理的目录中工作前，除根级规则外还要阅读该目录的局部指导。 - 当两份文档发生冲突时，遵循明确指定的唯一事实来源并报告冲突，不要将两者混合。 不得把模块级规则复制回根级文档。 应在能够完整拥有该规则的最窄层级更新规则，仅在便于查找时从更上层文档链接到它。 ## 改动前，先决定新代码和测试放在哪里 维护一份代码库地图，说明每个顶层区域拥有的内容，以及哪些依赖关系可以跨越其边界。 使用该地图决定新代码、测试、模板、文档和运行时数据的归属位置。 - 分离用户应用、共享契约、平台基础组件、编排工具、端到端测试和内容扩展。 - 使应用业务逻辑不了解进程控制和打包内部实现。 - 防止一个应用导入另一个应用的私有源代码或测试。 - 将跨运行环境的DTO、事件、错误和任务结构提升到纯共享契约层。 - 将测试放在其所验证层拥有的目录中；将跨应用一致性测试放在端到端层。 - 记录已移除或未启用的目录，避免贡献者误把过时架构重新创建出来。 如果某个可复用关注点没有明确所有者，应停止操作，并在创建另一个共享位置前取得所有权决定。 ## 只在一处决定数据存放位置，并直接传给其他部分 每个运行时根目录、命名空间和身份都只能在所属边界解析一次，然后把确定的值传递给下游。 组件必须使用该值，不得根据端口、工作目录、应用名称或环境回退值重新构造它。 - 所有运行时拥有的数据路径都应派生自已解析的数据根目录或由其派生的常量。 - 将范围有限的覆盖值和迁移来源视为明确例外，而不是备用根目录。 - 将临时传输细节与持久运行时身份分离。 - 在启动子进程前，为打包状态和开发状态分配命名空间。 - 将已解析状态传递给子进程；不要让子进程猜测自己的存储位置。 - 将已知的旧式逃逸路径记录为移除候选，绝不将其用作示例。 存在明确修复方式时，应通过规范根目录或显式参数传递路径。 正确所有权不明确时，应请求维护者决定，不要发明新的约定。 ## 把每个新功能同时加到应用和命令行中 围绕一个服务契约设计用户功能，并通过每个受支持的交互界面提供该功能。 界面之间的对等性属于功能完整性的一部分，而不是以后再补的增强项。 对于每项新功能： 1. 定义或更新共享的请求、响应、错误和事件契约。 2. 将服务端点实现为唯一的行为来源。 3. 添加调用该端点的图形界面。 4. 添加调用同一端点的命令行界面。 5. 适用时，提供机器可读的命令结果，以及用于长提示词的文件输入。 6. 更新更改检查清单，标明所有受影响的交互界面。 不得在不同客户端中实现彼此分歧的行为。 如果某个界面确实不适用，应在更改记录中说明理由，不得悄然省略。 ## 把界面组件做成可复用、人人都好用的样子 在保留有意设置的全局契约时，把视觉所有权交给最小且稳定的组件。 创建新的局部变体前，应优先复用共享基础组件。 - 将全局样式表保留为有意设置的导入边界和设计变量边界。 - 将组件拥有的样式放在组件旁边，并默认使用有作用域的模块。 - 全局选择器仅用于重置、设计变量、应用外壳、共享内容契约和第三方集成点。 - 拆分样式表时保持层叠顺序，并确认选择器优先级没有意外改变。 - 按钮、隐藏标签和通用表单行为应使用语义化控件及共享的无障碍基础组件。 - 只有需求确实可复用时才添加共享基础组件；产品特有布局应留在产品层。 - 退出动画很重要时，应让条件显示的元素继续挂载，并通过类切换状态。 - 优先使用快速的缓出动效、比进入更短的退出时长，以及非零的起始缩放比例。 如果附近的全局样式能够通过小型、可测试的更改安全迁移，应将其与组件一同移动。 不得把大范围机械迁移与无关的行为更改混在一起。 ## 用能发现问题的最轻测试来检查改动 选择能够观察该要求的最轻量验证层，仅在风险跨越边界时添加更广泛的检查。 验证必须与更改的所有权范围和用户影响相匹配。 - 对于缺陷，先编写可证伪的回归测试，并确认它在修复前失败。 - 将测试限定在报告的行为范围内；把相邻缺陷记录为单独的后续工作。 - 运行代码库守卫和静态检查，并为已更改的软件包执行有针对性的测试或构建。 - 对解析器或智能体事件流的更改，应先重放已记录会话，再消耗真实模型调用。 - 对单元测试无法证明的可见交互、动画或竞态行为，使用浏览器层检查。 - 对工作区或依赖项更改，刷新代码库要求的已生成链接和打包哈希。 - 相邻测试套件存在已知失败时，与基准状态进行比较。 让实现表达持久不变量，而不是历史例外。 当验收标准要求人眼可见的比较时，不得仅因自动检查通过就声称已经就绪。 ## 分开测试版和正式版，发布前检查要发出的版本 为每个交付渠道明确发布身份、打包行为和评审证据。 不得让方便的捷径抹去渠道隔离或绕过可信验证。 - 为开发、内部验证、预览和稳定渠道赋予不同的用途及公开身份。 - 明确定义晋级依赖；不要让稳定渠道依赖无关的预览流程。 - 保持打包运行时路径按命名空间隔离，并使其独立于临时端口。 - 让编排层调用所属软件包的基础组件，不要在调用方重新拼装进程参数或扫描规则。 - 更改说明必须陈述动机用例、用户可见效果、受影响界面和验证证据。 - 对可见界面更改，应附上展示功能入口的截图，而不只是孤立组件的图像。 - 将缺陷修复关联到相应回归测试和问题记录。 - 除非会妨碍正确性、安全性、数据完整性或契约兼容性，否则不要把无关发现加入当前更改。 发布前，应通过用户实际执行的同一路径验证产物。 不得批准违反代码库边界、缺少必要验证、暴露秘密或可能破坏持久数据的更改。