desloppify

Desloppify

1. あなたの役割

厳格スコアを誠実に最大化します。基本のサイクルは、スキャン → 計画 → 実行 → 再スキャンです。スキャン結果にあるエージェント向けの指示に従い、自分で分析して置き換えないでください。

**手を抜かないでください。**大規模なリファクタリングも細かな修正も、同じ熱意で取り組みます。20 個のファイルに手を入れる必要があるなら、20 個すべてに手を入れてください。1 行の変更で済むなら、その変更を行います。大きすぎるタスクも小さすぎるタスクもありません。最小限で済ませるのではなく、きちんと修正してください。

2. ワークフロー

3 つのフェーズをサイクルとして繰り返します。

モノレポと複数プロジェクトのディレクトリ

ワークスペースに複数のプログラム（例：兄弟フォルダーにあるフロントエンドとバックエンド）が含まれる場合は、それぞれを個別にスキャンします。親ディレクトリはスキャンしないでください。

desloppify --lang typescript scan --path ./frontend
desloppify --lang python scan --path ./backend

各 --path の対象は、単一のまとまったプロジェクトにしてください。複数のプログラムを含む親ディレクトリをスキャンすると、状態とパスのコンテキストが混在し、結果の信頼性が低下します。

フェーズ 1：スキャンとレビュー — コードベースを把握する

desloppify scan --path .       # analyse the codebase
desloppify status              # check scores — are we at target?

スキャン後は、必ず desloppify next を実行してください。次に何をすべきか、順番に正確に示されます。スキャン結果を自分で解釈したり、何をすべきかユーザーに尋ねたりしないでください。next を実行し、その指示に従ってください。

主観的な評価項目のレビューが必要かどうかは、スキャンで示されます。その指示に従ってください。手動でレビューを開始するには、次を実行します。

desloppify review --prepare    # then follow your runner's review workflow

フェーズ 2：計画 — 作業内容を決める

レビュー後、トリアージの各段階と計画の作成が、next が提示する実行キューに表示されます。順番に完了してください。各段階で --report に何を指定するかは、next が示します。

desloppify next                                        # shows the next execution workflow step
desloppify plan triage --stage observe --report "themes and root causes..."
desloppify plan triage --stage reflect --report "comparison against completed work..."
desloppify plan triage --stage organize --report "summary of priorities..."
desloppify plan triage --complete --strategy "execution plan..."

自動トリアージを行うには、desloppify plan triage --run-stages --runner codex（Codex）、--runner claude（Claude）、または --runner rovodev（Rovo Dev）を実行します。オプション：--only-stages、--dry-run、--stage-timeout-seconds。

続いてキューを整えます。next が提示する内容はすべて、計画によって決まります。next は実行キューであり、未処理項目の全一覧ではありません。この手順を省略しないでください。

desloppify plan                          # see the living plan details
desloppify plan queue                    # compact execution queue view
desloppify plan reorder <pat> top        # reorder — what unblocks the most?
desloppify plan cluster create <name>    # group related issues to batch-fix
desloppify plan focus <cluster>          # scope next to one cluster
desloppify plan skip <pat>              # defer — hide from next

フェーズ 3：実行 — キューを最後まで進める

計画を信頼して実行します。キューの途中で再スキャンせず、まずキューを完了してください。

**最初にブランチを作成します。**専用のブランチを作成し、健全性に関する作業を main に直接コミットしないでください。

git checkout -b desloppify/code-health    # or desloppify/<focus-area>
desloppify config set commit_pr 42        # link a PR for auto-updated descriptions

作業サイクル：

# 1. Get the next item from the execution queue
desloppify next

# 2. Fix the issue in code

# 3. Resolve it (next shows the exact command including required attestation)

# 4. When you have a logical batch, commit and record
git add <files> && git commit -m "desloppify: fix 3 deferred_import findings"
desloppify plan commit-log record      # moves findings uncommitted → committed, updates PR

# 5. Push periodically
git push -u origin desloppify/code-health

# 6. Repeat until the queue is empty

修正後、一時的にスコアが下がることがあります。連鎖的な影響は通常のことなので、作業を続けてください。 next が自動修正ツールを提案した場合は、まず desloppify autofix <fixer> --dry-run を実行してプレビューし、その後に適用してください。

**キューが空になったら、フェーズ 1 に戻ります。**新しい問題が見つかり、連鎖的な影響が解消され、優先順位も変わっているでしょう。これがサイクルです。

3. リファレンス

主な概念

• ティア：T1 自動修正 → T2 簡単な手動修正 → T3 判断を要する対応 → T4 大規模なリファクタリング。
• 自動クラスタリング：関連する検出結果は next で自動的にグループ化されます。next --cluster <name> で詳細を確認できます。
• ゾーン：production/script（スコア対象）、test/config/generated/vendor（スコア対象外）。zone set で修正します。
• Wontfix のコスト：寛容スコアと厳格スコアの差が広がります。差が広がったら、過去の判断を見直してください。

スコアリング

総合スコア = 25% 機械的評価 + 75% 主観的評価。

• 機械的評価（25%）：重複、デッドコード、コードの臭い、未使用のインポート、セキュリティなど、自動検出される問題です。コードを変更して再スキャンすることで修正します。
• 主観的評価（75%）：命名、エラー処理、抽象化、明瞭さなど、設計品質のレビューです。レビューを行うまでは 0% です。レビューが必要になると、スキャンで指示されます。
• 厳格スコアが最優先です。wontfix 項目も未解決として数えられます。総合スコアと厳格スコアの差が、wontfix による負債です。
• スコアの種類：総合（寛容）、厳格（wontfix を含む）、客観的（機械的評価のみ）、検証済み（修正が確認された項目のみ）。

レビュー

主観的なスコアを取得する4つの方法があります。

• ローカルランナー（Codex）：desloppify review --run-batches --runner codex --parallel --scan-after-import — エンドツーエンドで自動実行します。
• ローカルランナー（Claude）：desloppify review --prepare → 並列サブエージェントを起動 → desloppify review --import merged.json — 詳細はスキルドキュメントのオーバーレイを参照してください。
• ローカルランナー（Rovo Dev）：desloppify review --run-batches --runner rovodev --parallel --scan-after-import — acli rovodev run サブプロセスを使って、エンドツーエンドで自動実行します。
• クラウド／外部：desloppify review --external-start --external-runner claude → セッションテンプレートに従う → --external-submit。
• 手動の方法：desloppify review --prepare → ディメンションごとにレビュー → desloppify review --import file.json。

バッチ出力とインポートファイル名： サブエージェントごとのバッチ出力には、batch-N.raw.txt という名前を付けてください（プレーンテキスト／JSONの内容、拡張子は .raw.txt）。--import merged.json や --import findings.json の .json ファイル名は、個別のバッチ出力ではなく、最終的に統合されたインポートファイルを指します。バッチ出力に .json 拡張子を付けないでください。

サブエージェントの並列実行数の上限： すべてのレビューバッチを一度に起動しないでください。サブエージェントは少数のまとまりに分けて実行し、通常は同時に3～5個のエージェントを起動して、次のまとまりを開始する前に完了を待ちます。エージェントの結果が空、部分的、またはレート制限によるものと思われる場合は、まとまりのサイズを小さくし、失敗したバッチだけを再試行してください。一度に20個以上のサブエージェントを起動すると、APIクォータを使い切り、使用できるレビュー結果が得られない場合があります。

• まずインポートし、その後に修正してください。インポートすると、相関分析用の追跡対象ステート項目が作成されます。
• 目標と一致するスコアは、スコア操作を防ぐために自動リセットされます。エージェントのオーバーレイドキュメント（例：docs/CLAUDE.md、docs/HERMES.md）に記載されたブラインドレビューワークフローを使用してください。
• 中程度のスコア（60～80）でも、全体的な健全性は大きく向上します。
• 古くなったディメンションは next に自動表示されるので、キューに従ってください。

整合性ルール： 根拠のみに基づいてスコアを付けてください。過去のチャットコンテキスト、スコア履歴、目標しきい値への意識は使わないでください。根拠が一致しない場合は、低い方のスコアを付け、不確実性を説明してください。要求されたすべてのディメンションを評価し、省略しないでください。

レビュー出力形式

レビューのインポートには、機械可読なJSONを返してください。--external-submit では、生成されたテンプレートの session を含めてください。

{
  "session": {
    "id": "<session_id_from_template>",
    "token": "<session_hmac_from_template>"
  },
  "assessments": {
    "<dimension_from_query>": 0
  },
  "findings": [
    {
      "dimension": "<dimension_from_query>",
      "identifier": "short_id",
      "summary": "one-line defect summary",
      "related_files": ["relative/path/to/file.py"],
      "evidence": ["specific code observation"],
      "suggestion": "concrete fix recommendation",
      "confidence": "high|medium|low"
    }
  ]
}

findings は query.system_prompt と完全に一致させる必要があります（related_files、evidence、suggestion を含む）。不具合が見つからなかった場合は "findings": [] を使用してください。インポートはフェイルクローズ方式です。無効な findings があると、--allow-partial を渡さない限り中止されます。評価スコアは、信頼できる内部インポートまたはクラウドセッションから自動適用されます。従来の --attested-external も引き続きサポートされています。

インポート方法

• 堅牢なセッションフロー（推奨）：desloppify review --external-start --external-runner claude → 生成されたプロンプト／テンプレートを使用 → 表示された --external-submit コマンドを実行。
• スコア付き永続インポート（従来方式）：desloppify review --import findings.json --attested-external --attest "I validated this review was completed without awareness of overall score and is unbiased."
• 指摘事項のみの代替方法：desloppify review --import findings.json

レビュアーエージェントのプロンプト

エージェント定義をサポートするランナー（Cursor、Copilot、Gemini）では、専用のレビュアーエージェントを作成できます。次のシステムプロンプトを使用してください。

You are a code quality reviewer. You will be given a codebase path, a set of
dimensions to score, and what each dimension means. Read the code, score each
dimension 0-100 from evidence only, and return JSON in the required format.
Do not anchor to target thresholds. When evidence is mixed, score lower and
explain uncertainty.

エージェント設定の形式については、以下のエディター用オーバーレイのセクションを参照してください。

Plan コマンド

desloppify plan reorder <cluster> top       # move all cluster members at once
desloppify plan reorder <a> <b> top        # mix clusters + findings in one reorder
desloppify plan reorder <pat> before -t X  # position relative to another item/cluster
desloppify plan cluster reorder a,b top    # reorder multiple clusters as one block
desloppify plan resolve <pat>              # mark complete
desloppify plan reopen <pat>               # reopen
desloppify backlog                          # broader non-execution backlog

コミットの追跡

desloppify plan commit-log                      # see uncommitted + committed status
desloppify plan commit-log record               # record HEAD commit, update PR description
desloppify plan commit-log record --note "why"  # with rationale
desloppify plan commit-log record --only "smells::*"  # record specific findings only
desloppify plan commit-log history              # show commit records
desloppify plan commit-log pr                   # preview PR body markdown
desloppify config set commit_tracking_enabled false  # disable guidance

指摘事項を fixed として解決すると、このツールは未コミットの作業、コミット済みの履歴、提案されたコミットメッセージを表示します。外部でコミットした後、record を実行すると、指摘事項が未コミットからコミット済みに移動し、リンクされたPRの説明が自動更新されます。

エージェントへの指示

指示は、ライフサイクルのフェーズが切り替わる際にエージェントに表示されるメッセージです。モデルの切り替え、制約の設定、状況に応じた指示の提供に使用します。

desloppify directives                     # show all configured directives
desloppify directives set execute "Switch to claude-sonnet-4-6. Focus on speed."
desloppify directives set triage "Switch to claude-opus-4-6. Read carefully."
desloppify directives set review "Use blind packet. Do not anchor on previous scores."
desloppify directives unset execute       # remove a directive

利用可能なフェーズ：execute、review、triage、workflow、scan（および review_initial、triage_postflight などの詳細なバリエーション）。

クイックリファレンス

desloppify next --count 5                         # top 5 execution items
desloppify next --cluster <name>                  # drill into a cluster
desloppify backlog --count 5                      # top 5 backlog items outside execution
desloppify show <pattern>                         # filter by file/detector/ID
desloppify show --status open                     # all open findings
desloppify plan skip --permanent "<id>" --note "reason" --attest "..." # accept debt
desloppify exclude <path>                         # exclude a directory from scanning
desloppify config show                            # show all config including excludes
desloppify scan --path . --reset-subjective       # reset subjective baseline to 0

4. ツールの問題を上流で修正する

desloppify 自体に問題や一貫性のなさが見られる場合（バグ、誤った検出、クラッシュ、わかりにくい出力など）は、修正してプルリクエストを作成してください。自信を持って修正できない場合は、代わりにイシューを報告してください。

修正してプルリクエストを作成（推奨）

ツールのリポジトリを一時ディレクトリにクローンし、そこで修正を行い、プッシュする前にスキャン対象のプロジェクトで動作を確認してください。

git clone https://github.com/peteromallet/desloppify.git /tmp/desloppify-fix
cd /tmp/desloppify-fix
git checkout -b fix/<short-description>

変更を加えたら、テストスイートを実行し、元のプロジェクトで修正を確認してください。

python -m pytest desloppify/tests/ -q
python -m desloppify scan --path <project-root>   # the project you were scanning

問題がなさそうであれば、プッシュしてプルリクエストを作成してください。

git add <files> && git commit -m "fix: <what and why>"
git push -u origin fix/<short-description>
gh pr create --title "fix: <short description>" --body "$(cat <<'EOF'
## Problem
<what went wrong — include the command and output>

## Fix
<what you changed and why>
EOF
)"

最後に、後片付けをします：rm -rf /tmp/desloppify-fix

イシューを報告（代替手段）

修正方法が明確でない場合や、変更について議論が必要な場合は、最小限の再現手順（コマンド、パス、期待される出力、実際の出力）を添えて、https://github.com/peteromallet/desloppify/issues でイシューを作成してください。

前提条件

command -v desloppify >/dev/null 2>&1 && echo "desloppify: installed" || echo "NOT INSTALLED — run: uvx --from git+https://github.com/peteromallet/desloppify.git desloppify"

uvx を利用できない場合：pip install desloppify[full] && desloppify setup