archify-tuning

Archify のチューニング

ユーザーがシステムを説明し、エージェントが図を作成します。ソースの理解から実用的な成果物の提供まで、この一連の流れ全体を最適化してください。次の優先順位を守ってください。

1. 正確性：事実、関係、方向、条件、所有者、ソースがシステムと一致していること。
2. 読みやすさと見栄え：明確な読み進め方、区別しやすい接続、判読可能なテキスト、バランスの取れた構成。
3. 効率性：完了までの時間が短く、修正の失敗や作業の繰り返しが少ないこと。

テストとバリデーターはこれらの成果を支えるものであり、それ自体も改善の対象です。 チェックに合格しても図の品質が保証されるわけではありません。また、チェックの失敗から不適切なルールが明らかになることもあります。変更を決める前に、成果物と作成体験を評価してください。

製品要件と調整可能なルール

• ソースの事実と、ユーザーが実際に行えることを守ってください。初稿には誤りが含まれる場合があります。元の内容は保持し、ソースに裏付けられた修正や追加を記録してください。削除された要素の数は、意味内容の確認が必要なことを示す目安であり、編集の正誤を決めるものではありません。
• 間隔、推奨する方向、折れ曲がりの数、単一画面への収まりは、状況に応じて評価するデザイン上の方針として扱ってください。折れ曲がりが増えたり、スクロールが必要になったりしても、図全体の改善につながることがあります。合意された変更で対象となっていない限り、明示されたジオメトリと裏付けのある契約は維持してください。
• 失敗したチェックを修正する前に、それが防ごうとしているユーザーへの害を特定し、その害が実際に存在するかを確認してください。不適切なルールについては、適用範囲、しきい値、重大度を見直してください。廃止されたテストは、理由と実際の変更前後の証拠を添えて更新または廃止してください。元の失敗は見える状態に保ってください。期待値だけを変更しても、改善の証明にはなりません。
• 同じ要件を測定する場合、早期診断とブラウザーチェックの結果は一致させ、それぞれの適用範囲が異なる場合は、その違いを明示してください。どちらも無条件に正しい判断基準ではありません。信頼性の高い判定が難しい好みについては、ハードエラーにせず、推奨事項や目視確認の対象としてもかまいません。

指標

役割	指標	根拠
成果	正確で、視覚的にも許容できる最終成果物	ソースの監査と実際のスクリーンショット。機械的な合格と視覚的な受け入れを分けて評価します
成果	完了までの経過時間、修正の失敗、作業の繰り返し	タスク開始から、読み取り、初稿、修正、表示、納品までを記録した時間付きトレース
プロセス	初稿の品質と、最初に使える成果が得られるまでの時間	最初の試行、すべての失敗、最後に検証済みの使用可能な成果物を保持します
リグレッション	固定入力に対する合否と、出力の変化	replay.mjs、関連するテスト、視覚的な比較。レンダリングの合格は、finalize／ブラウザーでの受け入れを含みません
診断	折れ曲がり、交差、経路の長さ、テキストサイズ、CLI の所要時間	観察されたメリットやトレードオフを説明します。いずれも図全体の品質に代わるものではありません

納品済みの成果と、失敗または未完了のタスクは分けて報告してください。早く終了した失敗した実行は、速度向上ではありません。合成リグレッションは、固定された初稿の分母と分けて扱ってください。コーパスへの追加は、バージョン管理されたコホートを構成します。修正済みの初稿で、元のベンチマーク項目を置き換えてはいけません。

セットアップ

• チューニングの保存先：$ARCHIFY_TUNING_HOME。デフォルトは ~/.local/share/archify-tuning です。journal.md、bench/、rounds/、replays/ が保存されます。ドラフトにはソースプロジェクトの内容が含まれ、非公開の場合があるため、リポジトリの外に置きます。決してコミットしないでください。
• 再開：ジャーナル、利用可能なチェックポイント、現在の目標状態を読みます。中断状態と過去の製品上の決定を尊重し、重複して実施するのではなく、進行中のラウンドを続けます。ユーザーが選択した図の種類を使用し、共有の変更が影響する場合は他の種類も対象にします。
• バージョン：対象のリモートリビジョンを更新し、ソース、ベース、候補の識別情報を記録します。永続的に保持できる別々のワークツリー、または固定スナップショットを使用します。比較のベースラインや実行中の作成者のランタイムを上書きせずに、リモートの変更を記録します。
• エビデンスの選定：影響度に応じたエビデンスの選択に従います。変更されていないエビデンスは、元のリビジョンと適用範囲を保って再利用します。
• ツール：shots.mjs の実行には Node 22.13 以降と Chrome または Chromium が必要です（検出方法は ARCHIFY_CHROME で上書きできます）。コレクターは Devin CLI の履歴、または他のエージェントが出力した正規化済みトレースのエクスポートを受け付けます。他のエージェントの非公開の履歴データベースは読み取りません。

ループ

1. 問いの範囲を定める。 ジャーナルに、ユーザーに見える問題を1つ、仮説、それを支持または否定するエビデンス、時間と試行回数の上限を記録します。発生頻度、被害、期待される効果、継続的な複雑さに基づいて優先順位を付けます。別の生成を始める前に、既存のエビデンスを優先します。
2. 実験を選ぶ。 レンダラーやルールの変更には固定 JSON を、指示やフロー全体に関する主張には独立した比較可能な作成者を、問題の発見や転用可能性の確認には新しいプロジェクトを使用します。作成者による実行、タイミング、スクリーンショットを比較する場合は、実験の設計を読みます。問題の発見は、改善の証明ではありません。
3. 原因を特定する。 トレースのシグナルを使ってトレースを読み、図全体を確認します。主な原因、寄与要因、不確実性を記録します。ソースの誤解、配置、ルーティング、診断、指示の使いやすさ、不適切な受け入れルールを区別します。ルーターを非難する前に、適切な配置で再現します。ルールが文書化されているからといって、有用で適用しやすいとは限りません。
4. 責任のある範囲だけを最小限変更する。 ランタイムを修正する前に、最小限の再現を優先します。共有パスを変更する前に、他の呼び出し元を調べます。ルーティングと併せて、メインパスの配置、相互作用するモジュール、分岐・マージ用のスペース、戻り経路をまとめて評価します。実験的な配置はコピー上で行い、自動ルート修正では作成者が設定したピンを尊重します。実証された情報の不足に対してのみガイダンスを追加し、その後、作成者にとって有益かどうかを評価します。
5. 主張を検証する。 影響を受ける公開動作テストと固定入力を選び、既存のカバレッジで捉えられない実証済みのランタイム不具合には回帰テストを追加します。変更後の出力を同じビューポートと状態で確認します。変化した各合否結果を調査し、実際のリグレッション、誤った失敗の修正、エビデンスで裏付けられた意図的なルール変更を区別します。説明できない失敗は未解決のままです。局所的な改善を採用する前に、図全体と関連する対照ケースでも効果が維持されることを確認します。権威ある入力が変更された場合にのみ、生成済み出力を再構築します。
6. 結論を出して整理する。 確認できた事実、却下したアプローチ、残る問題、および次の区分のいずれか1つを記録します：問題を確認済み、局所的な修正を検証済み、実験候補、アプローチを却下、または独立レビューの準備ができた候補。視覚、速度、一般化に関する主張の限界を明記します。効果を確認できたら、レビューしやすい小さな変更を準備し、無関係な修正やプロトタイプは分けます。統合作業については CONTRIBUTING.md に従ってください。このスキルには、プッシュ、PR、マージ、リリース、稼働中のインストールを行う権限はありません。

実験を中止するタイミング

• 予算の上限に達したら、結果と残っている不確実性を記録します。具体的な新しい仮説があり、新たに範囲を限定したテストを行う場合に限り、予算を延長します。
• 因果関係を示す新たな証拠がないまま試行が繰り返される、プロジェクト固有の座標探索に依存する、選択した行は改善してもグラフ全体が悪化する、または得られる効果に対して複雑さが過剰に増す場合は、中止するか焦点を変えます。
• 最後に検証済みの成果物は、失敗した実験とは別に保存します。実験の終了は、全体の目標を達成したことを意味しません。次の作業を積み重ねる前に、有用な修正を統合します。

ツールと報告

リポジトリのルートから実行してください。以下のツールは選択した実験の根拠を得るためのものであり、毎回すべてを決まった順序で実行する必要はありません。round、collect、replay は引数なしで使用方法を表示します。

必要な作業	コマンド
固定入力の比較	node .agents/skills/archify-tuning/scripts/replay.mjs --base <base>/archify
作成者タスクの準備	node .agents/skills/archify-tuning/scripts/round.mjs <project-path> --types <selected-types> --archify <frozen-runtime>/archify
トレースとコンテンツ変更シグナルの収集	node .agents/skills/archify-tuning/scripts/collect.mjs <round> --dump（Devin の外では --trace-export <file.json> を追加）
初回のライトテーマ画像比較	node .agents/skills/archify-tuning/scripts/shots.mjs <replay-dir> --height 900

コレクターでは、意味上の正しさや経過時間の全体を確認できません。ソースのレビューと時間の記録で補完してください。失敗ログと不明な結果は保持します。診断では、影響を受けた要素と検証済みの修正を示すか、修正が見つからなかった理由を説明してください。作成時のガイダンスは簡潔にし、必読資料から参照できるようにします。確認された効果のない助言を蓄積しないでください。