av/facts

factsとは？

av/factsは、プロジェクトを.factsファイル内のatomic claims（原子的な主張）のリストとして管理するためのワークフローと仕様形式です。各行は、何が真であるべきかを示す短く構造化された記述で、オプションでマシンが主張を検証するためのshell commandを含められます。

主な目的は、エージェントとチームがプロジェクト要件を読みやすく検証可能に保つことです。粗い真実を書き、精密な仕様に洗練し、実施・検証します。facts checkを実行すると、どの主張がパス、失敗、手動対応が必要かを確認できます。

主な機能

• Atomic “fact”仕様形式（.facts）: プレーンテキストの文字列で1行1主張を記述し、ドメインごとにMarkdown見出しで整理。
• 進捗追跡のためのライフサイクルタグ: @draft、@spec、@implemented（およびカスタムタグ）を使用して、各主張のパイプライン位置を示す。
• コマンドベース検証: commandを含むfactsに対し、facts checkがコマンドを実行し、終了コード0で主張を真とみなす。
• 自動検証とステータスグループ化: facts checkがファイルをlintし、全コマンドを実行、結果をグループ化（例: 緑=パス、赤=失敗、黄=手動）；失敗時は非ゼロで終了。
• CI対応の終了コードとフィルタリング: タグ式（例: --tags "mvp and not blocked"）でチェックをフィルタし、仕様のサブセットを検証。
• エージェント管理のトランジションと仕様準拠実装: エージェントがfactsシートを読み、@spec factsをピックアップ、構築、facts check実行、パスしたものを@implementedにタグ付けし、仕様を自己更新。

factsの使い方

1. CLI/エージェントツールをインストール（Rustバイナリやnpxコマンドなど複数オプションあり、下記参照）。
   • 例: npx skills add av/facts
   • 次にエージェントにInit factsを実行（例: 「Init facts」）させ、スタックを検知し初期.factsファイルを作成。
2. .factsファイルを作成・編集（ドキュメント形式に従う）:
   • ドメインごとに見出しを追加（例: # auth、# data）。
   • 1行1主張を追加。
   • 各factにライフサイクルステージラベル（@draft、@spec、@implementedなど）を付与。
   • 検証可能主張には、主張が成り立つ際に0で終了するcommandを含める。
3. 検証実行: facts checkで全factsをlint・検証（--tagsで制限可）。パス、失敗、手動作業が必要なものを確認。
4. エージェントと反復: 粗いアイデアを@draftで書き、@specに洗練、エージェントに@spec factsを実装させ、facts checkパス後に@implementedにタグ付け。

ユースケース

• 変更後のプロジェクト仕様検証: 真であるべきチェックリストを維持、編集後にfacts checkで即座に確認。
• 要件を実行可能チェックに変換: 「真であるべき」記述（認証動作やデータ処理ルールなど）をコマンド検証付きfactsに変換。
• factライフサイクルでWIP管理: @draft → @spec → @implementedで進捗共有、各主張を実装・検証済みか明確に洗練対象化。
• 自動コードベース発見・分類: facts-discoverスキルでコードベースをスキャン、ライフサイクルステージでfacts分類、欠落真実追加。
• 仕様準拠実装: facts-implementフローでエージェントが@spec factsを読み、コード構築、facts check検証、タグ更新。

FAQ

factsはドキュメント形式だけ？ 実際に主張を検証する？ 両方可能: コマンドなしfactsはエージェントがコードベースで検証、コマンドありは実行し終了コード0で検証。

facts checkは何をする？ ファイルをlint、全コマンド実行、ステータス（パス/失敗/手動）でグループ化、失敗時は非ゼロ終了。

factsの整理・追跡方法は？ Markdown/YAML互換構造の.factsファイルに格納、ドメイン見出しとタグ（@draft、@spec、@implemented含む）でライフサイクル追跡。

プロジェクトの一部だけチェック可能？ はい。facts checkは--tagsでブール式フィルタ対応。

代替案

• テストスイート（ユニット/インテグレーションテスト）: 従来テストは動作検証可能だが、.factsは人間読みやすい原子主張とライフサイクル/ステータスパイプラインを重視、単なる自動パス/失敗でない。
• 静的ドキュメント + コードレビュー: ドキュメントは要件捕捉可能だが通常非実行、factsはfacts checkで主張を検証に紐付け。
• 要件トレーサビリティ対応仕様ツール: 実装紐付けツールはトレーサビリティ提供だが、factsは行単位主張形式、オプションコマンド実行、タグベースライフサイクル移行を特化。