エージェント向けの品質基準

dek はコーディングエージェントに使われることを前提に作っています。このページは、その使いやすさを測る基準です。変更しても損なってはいけないこと、改善で良くすべきことを定めます。コマンド、診断、規約を設計するとき、そしてレビューするときに参照してください。

エージェントの作業は、プロジェクトを把握し、スライドを書き、結果を確認し、問題を直し、デッキを作者に返す時機を判断する、という繰り返しです。以下の基準は、それぞれこの流れのどこかで作業が止まる原因に対応しています。

基準

1. 案内が正確である

AGENTS.md と dekc help --agent だけで作業を始められ、書かれている内容がプロジェクトの実際と一致していること。

• AGENTS.md に載っているクラス・トークン・レイアウトが、デッキが使うテーマに実在する。
• 作成したばかりのプロジェクトにも、エージェントに必要な案内がそろっている。
• レイアウトが想定する構造など、正しいマークアップを書くのに必要な情報は、この 2 つからたどれる。

2. 規約がすべて検査される

エージェント向けに書いた規約は、すべて lint ルールとして検査されること。lint を通ったデッキは、文書にある規約に違反していない。

lint が検査するのは、規約を守ろうとするエージェントが書くものです。すり抜けるために作った入力は対象外です。規約に従うつもりで一つ間違えたエージェントは捕まえます。一方、<iframe srcdoc> に隠した script や globalThis["Da" + "te"] のように、違反を隠すために仕立てたマークアップは扱いません。dek がビルドするのは自分で書いたか、エージェントに書かせたデッキで、見知らぬ人のデッキではありません。lint は規約チェッカーであって、サンドボックスではありません。

• AGENTS.md の規約は、それぞれルール ID に対応している。
• 検査できない規約は、検査できる形に直すか、規約から外す。
• ルールの挙動（重要度を含む）は、文書に書いたとおりである。

3. 描画結果を確認できる

人が画面を見なくても、エージェントが自分の描画結果を確認できること。

• はみ出しやコントラストのように幾何で判定できるものは、スクリーンショットの解釈に頼らず診断として返す。
• スクリーンショット、遷移の途中フレーム、いま表示中のスライドを、求めれば取得できる。
• 実行しなかった検査は「スキップ」と報告し、合格扱いにしない。

4. 診断から直し方がわかる

どの診断も、問題の場所と次にすべきことを示していること。

• 場所が正確である。直すべきファイルと、あれば行番号。
• hint は書いてあるとおりに実行できる。hint のコマンドは、その診断が出た状態で実行して成功する。
• hint が案内する先に、約束した情報がある。
• 他のスライドに問題を起こす修正を勧めない。

5. 結果を機械的に読める

エージェントが文章を解析しなくても、次の行動を決められること。

• 結果を返すコマンドはすべて --json を受け付け、同じ形で返す。
• 各診断が重要度を持ち、終了コードは重要度だけで決まる。
• ピクセル数、コントラスト比、問題の値などの数値は、メッセージの文中だけでなくフィールドとしても返す。

6. 止まりどころが明確である

測れる問題が残っていないこと、そして判断に残っているものが何かを、エージェントが見分けられ、少ない実行回数でそこに到達できること。

dekc lint --visual を通るのは、完成したデッキの必要条件であって十分条件ではありません。わかるのは、ルールで判定できるものに問題がないことだけです。スライドの釣り合い、話の筋、時間配分は、シートと台本を読んで判断し、最後は作者が決めます。

• 作成直後のプロジェクト、追加直後のデッキ、同梱のサンプルが、そのままで lint を通る。
• lint は見つけられる問題を一度にすべて報告する。1 件ずつ小出しにしない。
• warning は報告するが、実行を失敗させない。「未完成」を意味するのは error だけである。

7. 変更操作が安全である

ファイルを変更するコマンドは、エージェントが自然にたどり着くどの状態からでも動き、途中で止まった状態を残さないこと。

• どのファイルを先に編集していても、コマンドが動く。
• 失敗したコマンドは何も変更しない。
• 入力は、受け取った時点で検証する。後で使うときに初めて失敗させない。

8. 出力の表記がそろっている

同じ種類の情報は、どのコマンドでも同じ形で出ること。

• ソースのパスは、表示するすべての場所で作業ディレクトリからの相対パスにする。ビルドやスクリーンショットなど dek が書き出す成果物は、そのまま開けるよう絶対パスのままにする。
• 日本語を含んでも表の列がずれない。
• エラーと hint で同じ文言を繰り返さない。

違反の重要度

変更や不具合が基準に反するときは、エージェントへの影響で重要度を決めます。

重要度	エージェントへの影響
S1	作業が止まる。または、測れるはずの問題を「無い」と報告してしまう
S2	ゴールには着くが、実行回数や推測が増える
S3	表示上の問題だけで、作業は遅くならない

次に、エージェントがその違反にどう出会うかを見ます。ふつうの作業でたどり着くものは「自然」です。文書どおりにスライドを書く、hint に従う、たまたまの順でコマンドを実行する、といった場合です。穴を探すためにしか書かない入力が要るものは「作為的」です。

	自然	作為的
S1	新機能より先に直す	その箇所に手を入れるときに直す
S2	新機能より先に直す	その箇所に手を入れるときに直す
S3	余裕があるときに直す	余裕があるときに直す

難読化でしか届かない作為的な違反は対象外で（基準 2）、予定に入れず閉じます。