◉ANTIGRAVITY LABEN
記事一覧/Tips & 活用術
✦ Tips & 活用術/2026-11-19上級

雛形のリポジトリから次のサイトを立ち上げるとき、エージェントに手順書より先に渡す「罠の索引」の組み方

運用中のサイトを複製して次のサイトを立ち上げるとき、エージェントは直し方を持ち込んでも理由を置いてきます。症状・原因・直し方・正本の四列で引く罠の索引、複製前に一枚で決める持ち込みの計画、写しのずれを見つける点検を、実際に使っている三つのスクリプトとともに書き残します。

エージェント80雛形リポジトリ移植ドキュメント設計Next.js8個人開発128Antigravity419

✦ プレミアム記事

秋口のある晩、運用中のアーティストのサイトを複製して、次のサイトを立ち上げる準備をしておりました。章立ても、作品を横に送るギャラリーも、言語の振り分けも、ほとんどそのまま使えます。エージェントに「前のサイトと同じ作りで」と頼めば、一晩でかなりの所まで進むはずでした。

手が止まったのは、複製元の実装ノウハウの文書を開いたときです。日付つきの追記が節の外に散らばり始め、同じ趣旨の注意が、別の文書にも少し違う言い回しで書かれていました。どれが最新なのかを、書いた本人の私が即答できませんでした。この状態のまま渡せば、エージェントは三つのうちどれかを拾い、残りの二つとは違う直し方で直すでしょう。

それ以来、雛形から次を作るときは、手順書より先に「罠の索引」を一枚作って渡すようにしております。ここでは、その索引の一行の形、複製の前に決める持ち込みの計画、そして索引と正本がずれないための三つの点検スクリプトを、個人開発で実際に回している形のままお伝えします。

最初にお伝えしたいのは、索引には直し方を一行だけ書くということです

索引は、症状から引くための表です。一行は「症状・原因・直し方・正本」の四列だけにし、直し方は一行で止めます。なぜそう直すのか、どんな経緯で分かったのかは、正本の節に書いて、索引からはその節を指すだけにしています。

この分け方にたどり着くまで、私は索引にも理由を書き足しておりました。詰まった夜の記憶が新しいうちに、全部書いておきたくなるのです。結果は芳しくありませんでした。索引の行が育つほど、正本と索引の両方に同じ説明が並び、片方だけが直される——という二重管理が始まりました。

エージェントにとっても、索引が短いほうが扱いやすいのだと思います。症状の列で当たりを付け、正本の節を開いて理由を読み、それから直します。読む順番がはっきりしていれば、もっともらしい別解を自分で組み立てる余地が減ります。

一行の形と、実際に入っている行

私の索引に入っている行を、固有の名前を外して並べます。どれも、同じ型のサイトで実際に踏んだものです。

| 症状 | 原因 | 直し方 | 正本 |
| --- | --- | --- | --- |
| commit したのに push が「最新です」と言う | 同期フォルダ上の .git/index.lock の残骸で commit が黙って落ちた | git log --oneline -1 で HEAD を確かめる | rules.md §3 |
| デプロイが黙って失敗し、古い版のまま | 配信先の 1 ファイル 25MiB 上限を配布 PDF が超えた | 生成後に ls -l で大きさを見る | ops_guide.md §6 |
| 章の境目で背景がちらつく(iOS で顕著) | 交差監視の中央帯で現在の章を判定していた | 画面中央の点を含む章を現在の章にする | knowhow.md §2 |
| ライトテーマの暗い章で、切替ボタンの文字が消える | 反転するトークンのうち 1 つが漏れた | 暗い章ではトークン 6 つを 1 セットで反転 | knowhow.md §2.1 |
| ビルドが同期フォルダの上で 10 分以上止まる | 同期フォルダは書き込みが遅い | 手元のディスクへ写してビルドし、生成物だけ戻す | rules.md §3 |

四つ目の行には、索引を作ってから気づいたことが一つ含まれています。以前の私は、拡大表示の文字が消える不具合に「拡大表示だけは常に暗い地にする」という個別の回避策を当てていました。索引に並べてみると、それはトークンが一つ漏れていることの症状にすぎず、同じ根から別の場所でも文字が消えていたのです。回避策は索引に載せず、根のほうを一行で載せます。 これを決めてから、似た症状がまとまって引けるようになりました。

行の書き方で守っているのは三つです。

  • 症状は、画面で見えたままの言葉で(「レイアウトが崩れる」ではなく「切替ボタンの文字が消える」)
  • 原因は、仕組みの言葉で一文
  • 正本は、ファイルと節の番号まで
✦

ここまでお読みいただきありがとうございます。

この記事の続きを読む

この先には、実装コードやベンチマーク結果など、実務でお役に立てる内容をご用意しています。このサイトは広告を掲載しておらず、サーバーや開発にかかる費用はメンバーの皆様のご支援で成り立っています。もしお役に立てていましたら、ご支援いただけますと大変ありがたいです。

この記事で得られること
✦既存のリポジトリを雛形に次のプロジェクトを立ち上げる前に、過去に踏んだ罠を症状から引ける索引にまとめ、エージェントが同じ崩れを持ち込む前に止められるようになります
✦索引に理由まで書き足して二つ目の正本が育ち、どちらが新しいのか分からなくなる事態を、点検スクリプトで公開前に見つけられるようになります
✦複製した直後に雛形の固有値がどこに残っているかを数え、コメントに残した跡と本物の取り残しを分けて潰す手順を、自分のリポジトリで回せるようになります
Stripe による安全な決済 · いつでもキャンセル可能
✦

この記事を購入する

この先の内容をすべてお読みいただけます。一度のご購入で、いつでも何度でもアクセスできます。このサイトは広告を掲載しておらず、皆さまのご支援がサーバー費用などの運営を支えています。

または
メンバーシップなら全記事が読み放題 →
シェア

お読みいただきありがとうございます

Antigravity Lab は広告なしで運営しており、サーバー費用などの運営コストはメンバーシップのご支援で賄っています。実装コード・ベンチマーク・本番設計パターンなど、実務でお役立ていただける記事を毎日更新しています。もし読んでよかったと感じていただけましたら、ぜひご覧ください。

  • ✦コピー&ペーストで使える実装コード付き
  • ✦毎日新しい上級ガイドを追加
  • ✦¥580/月 または ¥1,480 の永久アクセス
メンバーシップを見る →

関連記事

✦ Tips & 活用術2026-11-17
srcset の sizes を小さく書くと画像まで縮む理由と、width・height 属性で横に伸びたときに足す CSS
レスポンシブ画像を入れた日に、作品画像が縮み、別の画像は横に伸びました。sizes が表示の大きさまで決める仕組み、width・height 属性を足すときの CSS 一行、額縁に縦長の絵を入れるときの sizes の割り出し方を、再現した数値と点検スクリプトで書き残します。
✦ Tips & 活用術2026-10-30
Linux で通った sed -i が iMac で止まった夜。エージェントの手順書を手元で動かす前の確かめ方
Linux の環境で動いた sed -i の手順を iMac で実行すると、置き換えが止まったり、バックアップが散らかったりします。GNU 版で再現した出力と、どちらでも動く書き方、実行前の確かめ方をまとめました。
✦ Tips & 活用術2026-10-23
本文リンクの入り口がない記事は 594 本ありました。関連記事の欄まで数え直すと、本当に孤立していたのは 6 本でした
MDX の本文リンクだけを数えると半数が孤立に見えました。関連記事の採点式を写して数え直し、ビルドで外されるリンクも拾う Python スクリプトの全文です。