entrix

Entrix 技能

目标：让目标仓库拥有可正常工作的 docs/fitness/ 配置，使其与实际工具链相符、能从仓库入口发现，并通过 Entrix 验证，而不是仅仅看起来像那么回事。

Entrix 中的 fitness 采用演进式架构的含义：一项可执行检查，用于衡量代码库是否仍满足质量或架构目标。面向用户的描述是“质量护栏”。

此技能现采用精简入口，并在 specs/ 下提供可复用的规范文件。请阅读这些规范，不要自行猜测架构细节。

技能文件夹内容

• specs/README.md：可用规范的二级索引
• specs/schema-frontmatter.spec.md：符合 Entrix 要求的证据文件格式
• specs/manifest.spec.md：manifest.yaml 的必需格式
• specs/dimension-boundaries.spec.md：如何拆分或合并维度
• specs/dimension-*.spec.md：各维度的指导说明
• examples/：可复制的最小示例片段
• ../../tests/fixtures/skill_regression/：技能回归测试框架使用的内置仓库配置

阅读顺序

对于任何初始化或修复任务，请按以下顺序阅读：

1. 目标仓库中存在的 AGENTS.md 和 CLAUDE.md
2. 目标仓库的清单文件和任务运行器： package.json、pyproject.toml、Cargo.toml、justfile、Makefile
3. 目标仓库的 .github/workflows/**
4. 目标仓库现有的 docs/fitness/**（如果存在）
5. 此技能的 specs/README.md
6. 仅阅读任务所需的特定 specs/dimension-*.spec.md 文件
7. 当入口文档或 CI 边界行为存在歧义时，阅读相匹配的 examples/*.md

核心规则

• 仅使用仓库中的真实信号。不要编造命令。
• 如果直接调用工具会依赖子目录作为工作目录，优先使用 just、make、npm run 或 cargo --manifest-path ... 等可在仓库根目录运行的封装命令。
• 优先使用已纳入版本控制的脚本和 CI 中确立的命令，而不是看似合理的默认值。
• 对于初始化输出，优先选择当前本地环境中可运行的命令，而不只是从 CI 或仓库结构来看在语义上正确的命令。
• 仅当仓库在脚本、CI 或已纳入版本控制的文档中有直接证据表明使用了某项工具时，才创建安全指标。不要想当然地添加常见扫描器。
• 如果某候选指标依赖未安装的可选本地工具，且没有已纳入版本控制的封装脚本可自动安装它，就不要将其设为默认的 fast 硬性门槛。应优先选择本地可运行的封装、仓库已确立的其他信号，或明确报告阻碍因素。
• 如果仓库的实际测试或构建命令具有权威性，但需要本地缺失的仓库专属开发依赖或 CI 配置，不要强行将其纳入默认本地 fast 层级。应优先选择本地可运行的冒烟检查，以及仅在 CI 中运行的权威指标。优先使用 execution_scope: ci，而不是将该命令保留为默认本地指标，以免其在全新机器上失败。
• 对缺失的编译器或运行时版本也采用同样的处理方式。如果仓库要求的 Rust、Node、Python 或类似工具链版本高于当前机器提供的版本，除非用户明确要求保留该阻碍，否则不要将这些命令设为默认本地指标。
• 仅使用符合 Entrix 要求的架构。不要自行发明其他清单或 frontmatter 格式。
• 如果加权维度参与评分，其文件级权重之和必须恰好为 100。
• 如果仓库有实际的构建、打包、Docker 或 CLI 冒烟检查信号，应明确考虑 release_readiness。
• 如果仓库提供契约或架构层，应明确考虑 api_contract。

架构规则

仅使用标准 Entrix 格式：

• 每个证据文件都使用 YAML frontmatter，包含：
  • dimension
  • weight
  • tier
  • threshold
  • metrics
• 维度使用 snake_case，例如：
  • code_quality
  • testability
  • release_readiness
  • api_contract
• manifest.yaml 使用：

schema: fitness-manifest-v1
evidence_files:
  - docs/fitness/code_quality.md
  - docs/fitness/testability.md

切勿使用：

• dimensions:
• 指标级别的 weight
• pass_threshold
• manifest.yaml 中不带路径的文件名
• 仓库已使用 Entrix 风格的 snake_case 时，使用带连字符的维度 ID

工作流

1. 检查目标仓库

从以下内容确定实际可执行的信号：

• 包管理器脚本
• 任务运行器，例如 just
• CI 工作流
• 已纳入版本控制的辅助脚本
• 现有的 docs/fitness/**

命令优先顺序：

1. 仓库中已有且本地使用的任务运行器或包脚本
2. 从 CI 中复制的根目录安全命令
3. 仅当仓库明确使用这些工具且工作目录明确时，才直接运行工具命令

2. 根据实际范围设计维度

常见的维度类别：

• code_quality
• testability 或 test_coverage
• security
• release_readiness
• api_contract
• ui_consistency
• design_system
• 运行时证据，例如 observability 或 performance

每个文件只保留一个稳定的关注点。如果仓库已经将不同关注点分开，就不要把它们合并成一个含糊的文件。

3. 编写易于发现的适配度文档

新仓库的最低输出要求：

• docs/fitness/README.md
• docs/fitness/manifest.yaml
• docs/fitness/review-triggers.yaml
• 至少包含 code_quality 和 testability，或另一个有明确依据的测试维度

保持仓库入口文件简短：

1. 如果存在 AGENTS.md，就在其中添加或修复简短的适配度章节
2. 如果存在 CLAUDE.md，也在其中添加或修复相同的简短适配度章节
3. 如果两者都存在，确保内容一致，不要只更新其中一个
4. 如果两者都不存在，则创建一个最简 AGENTS.md

创建规则很严格：

• 如果仓库原本没有 CLAUDE.md，不要新建
• 如果 CLAUDE.md 已是唯一的 Agent 入口文件，除非用户明确要求同时创建两个文件，否则不要新建 AGENTS.md
• 如果两者都不存在，则只创建 AGENTS.md

不要将整套规则复制到入口文件中。 目标是让仓库现有的每个 Agent 入口文档都能发现这些内容，而不只是你碰巧首先看到的那个。

4. 停止前进行验证和迭代

生成或修复 docs/fitness/ 后，你必须自行验证。

按以下顺序使用可用的最佳 Entrix 调用方式：

1. entrix ...
2. uvx --from entrix entrix ...
3. python3 -m entrix ...

运行：

entrix validate
entrix run --dry-run

如果存在 fast 层级，或者生成的命令执行成本较低，也请运行：

entrix run --tier fast

如果验证因你编写的文件而失败，请修复这些文件并重新运行验证。 不要在初稿完成后就停止。

必须执行修复循环：

1. 生成或修复 docs/fitness
2. 运行 entrix validate
3. 如果失败，重新读取 manifest.yaml 和每个证据文件
4. 修复架构、权重、路径和命令本地性问题
5. 再次运行 entrix validate
6. 运行 entrix run --dry-run
7. 如果验证通过，只要存在 fast 层级，或生成的命令足够轻量、可在本地执行，就运行 entrix run --tier fast
8. 如果 fast 层级因生成命令的本地性问题或虚构的信号而失败，请修复并重新运行验证
9. 如果 fast 层级因生成的指标需要本地无法运行的可选工具而失败，请将其替换为适合仓库且可运行的信号，将其移出引导用的 fast 层级，或明确报告阻碍因素
10. 如果仓库确实有测试／构建命令，但仅因本地环境缺少仓库专属开发依赖而失败，请勿将其纳入默认的本地 fast 层级；在适当情况下，为其设置 execution_scope: ci 或其他非本地权限边界
11. 只有在验证通过且生成的配置可运行，或存在明确的仓库阻碍因素时，才停止

5. 需要修复的典型失败模式

当验证报告总权重为 0% 或 No metrics matched 时，请检查：

• frontmatter 分隔符错误
• manifest 结构错误
• manifest 条目使用了裸文件名，而非相对于仓库的路径
• 使用了 pass_threshold 等非标准键
• 缺少文件级 weight
• 维度名称不符合 Entrix 约定

当生成的命令语义有误时，请检查：

• 仓库的 Cargo.toml 实际位于子目录中，却在根目录运行命令
• 仓库指南优先推荐 just test，而非原始的 cargo nextest 变体
• 虚构了仓库实际并未使用的安全工具
• 构建命令与仓库实际的发布／构建流程不同
• 从 CI 复制的命令隐式依赖于工作流专属的工作目录
• 可选工具链检查在原理上确实存在，但如果不进行额外且未声明的设置，就无法从目标仓库在本地运行
• 确实存在的测试命令需要当前本地环境尚未安装的开发依赖，尽管 CI 或贡献者文档对此有所要求
• 已存在 AGENTS.md 和 CLAUDE.md 文件，但生成的输出只更新了其中一个
• 仓库只有 CLAUDE.md，但生成的输出却自行新增了 AGENTS.md

质量标准

只有满足以下所有条件，这项技能才算完整：

• docs/fitness/ 存在且内容连贯
• docs/fitness/README.md 存在
• manifest.yaml 包含 schema: fitness-manifest-v1
• manifest.yaml 列出了相对于仓库根目录的证据文件路径
• 现有仓库入口文档 AGENTS.md 和 CLAUDE.md 均一致地指向质量评估文档
• 除非用户明确要求，否则未创建额外的 Agent 入口文档
• 权重总和为 100
• 每项指标都对应一个实际的仓库命令
• 技能选择的每项 fast 硬性门槛都能在本地运行，或者被明确指出是具体的仓库阻碍
• 仅在 CI 或预置环境中具有权威性的命令，均按此建模，而非假装它们是默认的本地快速检查
• 除非用户明确要求包含这类范围，否则默认的本地 entrix run 不会执行仅限 CI 的指标
• 默认的本地 entrix run 整体能够通过；预期在本地失败的软性或建议性指标应限定为 CI 范围、权重设为零，或采用其他建模方式，以免本地得分低于阈值
• 已尝试使用 Entrix 进行验证
• 如果有成本较低的快速层级运行方式，已对生成的配置进行超出 dry-run 的测试
• 已修复由生成文件导致的验证失败

避免

• 质量评估文档无法从 Agent 入口文档中找到
• 臆造 Entrix 无法解析的替代架构
• 臆造仓库未使用的安全或覆盖率工具
• 在存在可安全从仓库根目录运行的包装脚本时，使用依赖子目录的原始命令
• 仅生成看似合理的文件便停止