entrix

Entrix スキル

目標：実際のツールに合致し、リポジトリのエントリーポイントから見つけやすく、見た目だけそれらしいのではなく Entrix の検証に合格する、動作する docs/fitness/ 設定を対象リポジトリに用意します。

Entrix における fitness は、進化的アーキテクチャの意味で使われています。これは、コードベースが品質またはアーキテクチャ上の目標を引き続き満たしているかを測定する、実行可能なチェックです。ユーザー向けの説明は「品質ガードレール」です。

このスキルでは、小さなエントリーポイントと、specs/ にある再利用可能な仕様ファイルを使用します。スキーマの詳細を推測せず、これらの仕様を読んでください。

スキルフォルダーの内容

• specs/README.md：利用可能な仕様の第 2 階層の一覧
• 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 互換のスキーマのみを使用してください。別形式のマニフェストやフロントマターを作り出さないでください。
• 重み付きディメンションがスコアに含まれる場合、ファイルレベルの重みの合計を正確に 100 にしてください。
• リポジトリに実際のビルド、パッケージ、Docker、または CLI のスモークシグナルがある場合は、release_readiness を明示的に検討してください。
• リポジトリにコントラクトまたはスキーマの対象範囲がある場合は、api_contract を明示的に検討してください。

スキーマのルール

標準の Entrix 形式のみを使用してください。

• 各エビデンスファイルでは、YAML フロントマターに次の項目を使用します。
  • 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 などのランタイムエビデンス

1 つのファイルにつき、安定した関心事を 1 つにしてください。リポジトリですでに関心事が分けられている場合は、曖昧な 1 つのファイルにまとめないでください。

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 のみがエージェントのエントリーポイントとして存在する場合、ユーザーから両方を明示的に求められない限り、新たに AGENTS.md を作成しないでください。
• どちらもない場合は、AGENTS.md のみを作成してください。

ルールブック全体をエントリーポイントファイルに複製しないでください。 目的は、最初に目に入ったファイルだけでなく、リポジトリですでに使用されているすべてのエージェント用エントリードキュメントから、フィットネスドキュメントを見つけやすくすることです。

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. 検証に合格した場合は、そのティアが存在する場合、または生成されたコマンドをローカルで安価に実行できる場合に、entrix run --tier fast を実行する
8. 生成されたコマンドのローカル性、または捏造されたシグナルが原因で fast ティアに失敗した場合は、修正して検証を再実行する
9. 生成されたメトリクスに、ローカルで実行できないオプションのツールが必要なため fast ティアに失敗した場合は、リポジトリで安全に実行できるシグナルに置き換えるか、ブートストラップ用の fast ティアから外すか、ブロッカーを明示的に報告する
10. リポジトリに実際のテスト／ビルドコマンドが存在しても、ローカル環境にリポジトリ固有の開発依存関係がないためにのみ失敗する場合は、デフォルトのローカル fast ティアから外し、適切であれば execution_scope: ci または別の非ローカルな実行境界としてモデル化する
11. 検証に合格し、生成された設定が実行可能になるか、具体的なリポジトリのブロッカーが判明するまで停止しない

5. 修正すべき一般的な失敗パターン

検証結果が合計重み 0% または No metrics matched を示す場合は、次を確認してください。

• フロントマターの区切り文字が誤っている
• マニフェストの構造が誤っている
• マニフェストのエントリで、リポジトリ相対パスではなくファイル名だけを使用している
• pass_threshold などの標準外のキーを使用している
• ファイルレベルの weight がない
• ディメンション名が Entrix の規約に合っていない

生成されたコマンドの意味が誤っている場合は、次を確認してください。

• 実際の Cargo.toml がサブディレクトリにあるリポジトリに対して、ルートレベルのコマンドを実行している
• リポジトリのガイダンスでは、生の cargo nextest 系コマンドより just test が推奨されている
• リポジトリで実際には使用されていない架空のセキュリティツール
• リポジトリの実際のリリース／ビルド手順と異なるビルドコマンド
• 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 のうち、リポジトリに存在するすべてのエントリードキュメントから、フィットネスのドキュメントへ一貫して案内されている
• ユーザーから明示的に依頼されていない限り、追加のエージェントエントリードキュメントを作成していない
• 重みの合計が 100 である
• すべてのメトリクスが、実際に存在するリポジトリのコマンドに対応している
• スキルが選んだ fast のハードゲートはすべてローカルで実行可能であるか、具体的なリポジトリ上の阻害要因として明記されている
• CI またはプロビジョニング済み環境でのみ正式な結果となるコマンドは、デフォルトのローカル fast チェックであるかのように扱わず、その条件に合わせてモデル化されている
• ユーザーから明示的にその範囲を依頼されていない限り、デフォルトのローカル entrix run では CI 専用のメトリクスを実行しない
• デフォルトのローカル entrix run は全体として成功する。ローカルでの失敗が想定されるソフトまたは参考用のメトリクスは、CI 対象、重みゼロ、またはローカルのスコアをしきい値未満にしない別の方法でモデル化されている
• Entrix 自体を使った検証を試みている
• 安価に実行できる fast ティアのチェックがある場合、生成した設定を dry-run 以外でも実行している
• 生成ファイルが原因の検証失敗を修正している

避けること

• エージェントのエントリードキュメントからフィットネスが見つけられない状態にする
• Entrix が解析できない別のスキーマを考案する
• リポジトリで使われていないセキュリティツールやカバレッジツールを考案する
• リポジトリルートから安全に実行できるラッパーがあるのに、サブディレクトリに依存するコマンドをそのまま使う
• 妥当に見えるファイルを作成しただけで終える