Claude Code Harness Smoke Test: エージェントに任せる前の15分検証ループ

Claude Codeを本番に近い作業で使うとき、最初に必要なのは大きな自動化ではありません。必要なのは小さく壊れない smoke test です。読むファイル、触ってよいファイル、絶対に触らない領域、最後に見る証跡を先に決めるだけで、エージェント作業の危険度は大きく下がります。

この記事の検索意図は、Claude Codeを使い始めた人が「どこまで任せてよいか」を判断したい場面です。PVだけでなく無料PDF登録、Gumroad教材、導入相談につなげたいサイトでは、コードの成功だけでなくCTAの成功も同じ run card に入れる必要があります。

あわせて読む: Claude Code harness engineering, first repo audit checklist, permission safety ladder.

なぜこの型が効くのか

harness smoke test は、エージェントの能力を信じるためではなく、作業環境の境界を確認するために使います。小さな記事修正でも、無料PDFフォーム、Gumroadリンク、導入相談リンクが壊れれば収益導線は失われます。

15分の検証なら毎回続けられます。最初から完全なCIを作るのではなく、読み取り、限定編集、build、公開URL、スクショの順に小さく通します。

実務フロー

1. 今回の目的を1文で書き、編集対象を3ファイル以内に絞る
2. 秘密情報、課金、顧客データ、デプロイ設定を禁止領域として書く
3. build、差分、公開URL、スクショのどれで完了を判断するか決める
4. 記事やLPなら、無料PDF、Gumroad、導入相談CTAも確認対象に入れる
5. 完了後に run card を残し、翌日の改善で再利用する

場面	安全な進め方	確認
新規記事	本文とfrontmatterだけ許可し、レイアウトやAPIは読取専用にする	buildと公開URL
商品ページ	リンク文言とカード順だけを変更し、決済URLは照合する	Gumroadリンク確認
チーム導入	最初はread-onlyで監査し、次に1つの安全な編集だけ許可する	差分とスクショ

そのまま使えるプロンプトとコード

このリポジトリで15分の harness smoke test を実行してください。まだ大きな編集はしないでください。目的、編集可能ファイル、禁止領域、検証コマンド、公開URL、無料PDF/Gumroad/相談CTAの確認項目を返してください。

const runCard = {
  slug: "claude-code-harness-smoke-test-loop",
  goal: "publish one safe content change",
  allowedFiles: ["site/src/content/blog-en/example.mdx"],
  blockedAreas: [".env", "billing/", "cloudflare/"],
  proof: ["npm.cmd run build", "public URL screenshot"],
  ctas: ["free PDF", "Setup Guide", "consultation"]
};

function readyForAgent(card) {
  return card.allowedFiles.length > 0 &&
    card.blockedAreas.length > 0 &&
    card.proof.some((item) => item.includes("build")) &&
    card.ctas.length >= 3;
}

console.log(readyForAgent(runCard) ? "ready" : "tighten scope");

このコードは、作業依頼を小さな run card に落とす例です。実際の自動化では、この形をPRテンプレート、記事公開チェック、導入相談前の診断メモに流用できます。

3つの実例

Astro記事公開

記事本文、heroImage、CTAだけを変更対象にします。buildが通っても、公開URLでh1とCTAが別記事なら失敗です。

小さなUI修正

ボタンの文言を変えるだけでも、モバイル幅で折り返しとクリック領域を見ます。商品導線のボタンならリンク先も一緒に確認します。

社内導入の初回

最初の会ではコードを書かせず、README、権限、テスト、禁止領域を整理します。相談に進む読者には、この整理結果がそのまま持ち物になります。

避けたい失敗例

• 最初の依頼で「全部改善して」と書くと、範囲が広がりすぎます。
• buildだけで終えると、公開環境のfallbackや古いCTAを見落とします。
• Gumroadリンクを記事ごとに確認しないと、初心者記事が上級者商品へ飛ぶことがあります。

特に多言語記事では、slugが揃っていても本文とCTAだけ古いことがあります。ローカルのfrontmatterだけで判断せず、公開URLの画面で確認します。

無料PDF / Gumroad / 導入相談へのつなぎ方

操作に慣れていない読者には、まず 無料チートシート を案内します。権限、CLAUDE.md、hooks、MCP、CIまで整えたい読者には Setup Guide が合います。

繰り返し使うレビューやデバッグ依頼で止まる読者には 50 Prompt Templates を出します。チーム展開や実リポジトリの運用設計が必要なら 導入相談 に進めます。比較したい読者は 商品一覧 から選べます。

公開前後に見るところ

公開前はfrontmatter、heroImage、内部リンク、Gumroadリンクを見ます。公開後はスマホ幅でh1、本文冒頭、CTA付近を確認し、HTTP 200でも別記事やトップページfallbackなら未公開として扱います。

次に見る数字

このslugでは、検索流入、無料PDF開始数、Gumroadクリック、商品ページ遷移、導入相談ページ遷移を見ます。PVが増えても商品クリックが増えなければ、読者の段階とCTAがずれています。

30分運用レビューで確認すること

harness smoke testを実務に入れるときは、記事を読み終えた直後よりも、翌日の運用レビューが重要です。まず前日のログを見て、Claude Codeに任せた範囲、実際に変更されたファイル、実行した検証、公開後に見た画面を1つのメモにまとめます。ここで曖昧な言葉を残さないことが大切です。「確認した」ではなく「スマホ幅でh1、本文冒頭、CTA、Gumroadリンクを見た」と書けば、翌日も同じ品質で再現できます。

次に、読者の行動と作業者の安心を分けて見ます。作業者側では、禁止領域に触れていないこと、buildと公開URLが同じslugを指していること、翻訳本文が英語のまま残っていないことを確認します。読者側では、無料PDFへ進む人、Gumroad教材を見る人、導入相談へ進む人がどの段落の後で動きそうかを考えます。PVが増えてもこの分岐が弱ければ、記事はまだ収益導線として完成していません。

最後に、次回のClaude Code依頼へ戻せる形にします。失敗があれば「次回はこのファイルをask-beforeにする」「このCTAは公開URLで必ずクリックする」「この言語はスクショで本文冒頭を拡大して見る」のように、1つだけルールを足します。ルールを一気に増やすと運用されません。小さなルールを毎日1つ足す方が、記事品質、商品導線、多言語公開のすべてで効果が残ります。

小さな検証ログを残す

この型を続けるなら、最後に1行だけ検証ログを残します。書く内容は、作業日、slug、主CTA、build結果、公開URL、スクショで見た言語、次に直す候補です。長い日報にする必要はありません。むしろ短い方が翌日読み返せます。Claude Codeに次の作業を頼むときも、この1行があるだけで「前回どこまで確認したか」「どの商品導線を強めたか」「どの言語を必ず見るべきか」がすぐ伝わります。記事運用は毎回ゼロから考えると崩れます。小さなログを積むほど、無料PDF、Gumroad、導入相談の導線も改善しやすくなります。

翌週に直す優先順位

翌週の改善では、最初に流入がある記事を見ます。PVが少ない記事に大きな変更を入れるより、すでに検索されている記事でCTAの迷いを減らす方が成果につながります。無料PDFのクリックがあるのにGumroadへ進まないなら、商品説明の前に「どの作業が楽になるのか」を1段落足します。Gumroadはクリックされるのに購入が弱いなら、記事側で価格ではなく成果物を具体化します。相談ページへ進む読者がいるなら、問い合わせ前に準備する情報を記事内で説明します。この順番で見ると、Claude Codeの記事改善が単なるリライトではなく、収益導線の改善になります。

最後の判断基準

最後は「読者が次の作業を選べるか」で判断します。読み終えた人が、無料PDFで試す、Gumroad教材で型を手元に置く、導入相談で自分の運用に落とす、のどれかを自然に選べるなら記事は役に立っています。どれも選べないなら、情報は多くても導線は弱いままです。

公開後の確認で迷ったら、PVよりも読者が次の行動へ進めたかを優先して判断します。