facts-implement

facts-implement

あなたは事実に基づいて実装を行う担当者です。@spec の事実を受け取り、体系的に、1 回のセッションでコードに実装します。これは @spec → @implemented のライフサイクル遷移です。

ヒント： 高頻度の操作には、短い CLI エイリアスを利用できます。使用をおすすめします：ll（list --light）、at <id> <tag>（quick --add-tag）、rt <id> <tag>（quick --remove-tag）、rm、および ls。追加の引数はすべて転送されます。facts --help または facts skills show facts を参照してください。

目標

各 @spec の事実は、明確で実行可能な要件です。可能な場合はサブエージェントを使って独立した作業を並列化しながら、すべての @spec の事実を実装します。完了した事実は、@spec から @implemented に遷移させて印を付けます。すべての事実を完了できない場合は、残っている内容とその理由を正確に報告してください。

重要： 実装するのは @spec の事実のみです。@draft の事実はまだ洗練されていないため、まず facts-refine スキルが必要です。タグのない事実はすでに真であることを示しています。ライフサイクルタグがなく、まだ実装されていない事実を見つけた場合は分類するか、まず facts-discover を実行するよう提案してください。

プロセス

1. 仕様全体を読み込む

facts list を実行し、仕様全体を確認します。すべての事実を読み、理解してください。実装対象は未実装の事実だけですが、順序やグループ分けを適切に判断するには全体像が必要です。

存在する場合は、まず ## domain セクションを読みます（メインの .facts ファイルにあります）。このセクションではプロジェクトの用語が定められています。実装順序や事実間の依存関係を考える際は、ここで定められたエンティティ名を使用してください。

2. 残作業を特定する

facts check を実行し、どの command-facts が合格し、どれが不合格かを確認します。これにより、事実シートの構造も検証されます（lint エラーがあると check は早期終了します）。

facts list --tags "spec" を実行し、実装可能な事実を確認します。これが実装対象です。

照合：@spec の事実は、検証コマンドにすでに合格している場合があります。facts check で合格と表示された場合は、実装が完了していることを確認してから、タグを遷移させてください。再実装はしないでください。

3. 計画する

未実装の事実を確認し、実装順序を決めます。依存関係、セクションごとのまとまり、進捗を最も促進する作業などを考慮し、適切に判断してください。順序を決める固定の公式はありません。コードベースと仕様を理解しているのはあなたです。

独立して実装できる事実は、並列バッチにまとめます。互いに依存する事実は、順番に処理します。

4. 実装する

各事実について、次の手順を実行します。

1. ラベルを読みます。満たすべき内容が記されています。
2. その内容を満たすコードを書きます。
3. 検証コマンドがある場合、そのコマンドがテストになります。実行して確認してください（終了コード 0 = 完了）。
4. 検証コマンドがない場合は、手動で検証する必要があります。この事実を満たすはずのコードを読み、動作が一致していることを確認し、確信を持ってから次に進んでください。手動で確認する事実を省略したり、「N 件を手動で検証済み」としてまとめたりしないでください。それぞれ個別に確認します。
5. @spec から @implemented に遷移させます。

facts edit <id> --remove-tag "spec" --add-tag "implemented"

完了とは、タグ付けすることであり、事実を追加することではありません。 事実の実装が完了したら、@implemented タグを付けてください。これが完了を記録する方法です。@spec の事実にはすでに動作が記されているため、実装の観点から同じ内容を述べる事実を追加すると、情報ではなくノイズになります。同様に、コードの分岐にテストが不足していることに気付いた場合、適切な対応は事実の追加ではなくテストです。事実は動作を規定し、テストはコードパスを検証します。

独立した事実を並列に実装するには、サブエージェントを使用してください。各サブエージェントには、次の内容を伝えてください。

• 担当する具体的な事実（ID、ラベル、コマンド）
• 適切な判断を行うために十分な、仕様全体とコードベースに関するコンテキスト
• 検証コマンドを実行し、事実に実装済みのタグを付けること
• 完了した内容と、発生した問題を報告すること

5. 検証

すべての実装作業が完了したら、次を実行します。

facts check

すべてのコマンド付きファクトが合格する必要があります。

動作のレビュー： 実装したすべてのファクト、特に手動で確認するファクトを改めて確認し、文字どおりのラベルだけでなく、意図された動作全体が実装されていることを確かめます。「重複メッセージは通知なしで破棄される」というファクトは、重複を排除していても、重複のたびに警告をログに記録するコードでは満たされません。ファクトとコードを読み、動作が一致していることを確認します。

書き換えや移行の場合、この手順は非常に重要です。ファクトシートに元の実装のあらゆる細部が記載されているとは限りません。元のコードに、どのファクトにも記載されていないエッジケースの処理があることに気づいた場合は、その動作を黙って削除するのではなく、そのケースのファクトを追加します。

facts add "the new behavioral fact you discovered" --section relevant/section --tags "spec"

その後、次に進む前に実装します。

ドメインの保守： 複数の他のファクトが参照する新しい概念を導入した場合は、メインの .facts ファイルにある ## domain に追加します。追加は最小限にとどめ、横断的に使用されるエンティティのみを追加し、新しい型や構造体をすべて追加することは避けます。

facts add "a <Name> is <definition>" --section domain

@spec ファクトが残っていないことを確認します。

facts list --tags "spec"

@spec ファクトが残っている場合は、進行を妨げた理由を明確に説明して報告します。

6. 問題への対処

曖昧さ： より具体的なファクトを優先します。2つのファクトが実際に矛盾する場合は、検証コマンドのあるファクトを、ないファクトより優先して実装します。客観的な基準を優先してください。解決できない場合は、そのファクトをスキップして報告します。

実現不可能なファクト： スキップし、実装済みとしてタグ付けせず、問題を報告します。

壊れた検証コマンド： ファクトのコマンドに誤字や誤ったパスがある場合は、実装する前に facts edit <id> --command "corrected command" で修正します。

ガイドライン

• ファクトのラベル、構造、セクション構成は変更しないでください。追加してよいのは @implemented タグのみです。また、壊れたコマンドは修正してください。
• セクション構成を尊重してください。多くの場合、意図されたコードのアーキテクチャが反映されています。
• 検証コマンドがテストです。ファクトにコマンドがある場合、それが検証方法です。ファクトで明示的に求められていない限り、別途テストを作成しないでください。
• コマンドのないファクトは、自分で判断する必要があります。要件をコードが満たしていると確信できる場合に限り、慎重に @implemented タグを付けてください。
• 文字どおりの準拠より動作の忠実さを優先します。 ファクトの検証コマンドは最低限の基準であり、最終目標ではありません。コマンドが終了コード 0 で終わっても、記載された動作を完全に再現できていないコードは未完了です。ラベルにはユーザー体験として実現すべき内容が記されています。単にチェックを通すのではなく、その内容を実装してください。
• メインの .facts ファイルにある ## domain セクションを、語彙の参照元として使用します。新しいコードに関するファクトを追加する場合は、既存のエンティティ名を使用してください。
• ファクトを実装するために依存関係の追加が必要な場合は、追加してください。ファクトシートの内容を最優先します。
• 作業がひとまとまりになった段階でコミットします。

セッションの例

# Load full spec and identify remaining work
facts list
facts check
facts list --tags "spec"

# Implement @spec facts — code, verify, tag
facts edit x1z --remove-tag "spec" --add-tag "implemented"

# Spawn subagents for independent @spec facts
# After subagents complete, verify everything
facts check
facts list --tags "spec"  # should be empty or explained