Urazuke — 進化・修正の道:方法で生まれなかったシステムを正常化し、それからはしごを登る

著者:Pablo Kuschniroff、Claude Codeの支援による。第1版、2026年10月18日。このページは方法の後半だ:主文書は新規プロジェクトの道を記述し、ここではシステムが既に存在し、それを作ったのが他人(あるいは証拠なしに「バイブコーディング」した私自身)で、今それを修正するか成長させなければならないときに私が何をするかを記述する。見慣れない言葉は主文書の用語集にあり、実際の事例は参照文書にある。公開リポジトリ:github.com/pkuschnirof/urazuke。

なぜこのページが存在するか

はしごを書いたとき、私は空のフォルダを見ながら書いた:第0段はプロジェクトに取り組むかを決め、第4段は機能のない骨組みをデプロイし、第5段になってようやくユーザーが見る最初のものが現れる。きれいな場合であり、最もよく教える場合でもある。だが最も頻繁な場合ではない。実務では、誰かが私を呼ぶときの大半は、既に動いていて、それに依存するユーザーがいて、もういない誰か、あるいは誰も証拠を求めなかったモデルが作ったシステムがあり、依頼は「これを直して」か「あれを足して」だ。私自身のツールは、はしごが書かれるずっと前から診断モードで他人のシステムに入っていたし Ref. 11、方法が初めて本番のシステムから栄養を得たのは、既に存在していたものを見ているときだった Ref. 12。

そしてここに、先へ進む前に名指ししておきたい罠がある:レガシーを前にした誘惑は、どちらも間違っている二つの極端のどちらかを選ぶことだ。一つは「方法でゼロから書き直す」:きれいに聞こえるし、ほとんど常に、最初のシステムを置き換えるに至らない二番目のシステムで終わる。もう一つは「直接ループを当てる、そのために第5段から第12段があるのだから」:実際的に聞こえるが、砂の上に建てることだ。ループは契約が、地図が、テスト環境が、動くテスト群が、繰り返せるデプロイが存在することを前提にしているからだ。方法で生まれなかったシステムには、そのどれも存在しない。この道は真ん中を行くものだ:まず正常化し、書き直さず、それからはしごを登る。

方法の三つのユースケース

方法には三つのユースケースがあり、エージェントを開く前にどれにいるかを知っておくとよい。どこから入るかが変わるからだ。

ケース出発点どこから入るか最初の機能の前に何があるかどこに書かれているか
新規プロジェクト空のフォルダと依頼を持つオーナー。第0段、そこから二十四を順に。最初の機能の前に立ち上げの区間まるごと。主文書、二十四の契約、コースのマニュアル。
方法で作られたシステムへの進化・修正システムは既にはしごを登っている:契約、地図、証拠付きで閉じた保留項目、テスト群、デプロイ、マニュアルがある。第5段:ブロックを開いてループを辿る。第13段は定期的に。第23段は段階の締めに。なし:次の段階のために第23段が第0段へ戻るだけで、既に主文書のパートBにある。主文書(フェーズ4、運用)。
方法なしで作られたシステムへの進化・修正動いていて、ユーザーがいて、それらの成果物が一つもないか、いくつかが中途半端なシステム。このページの正常化の区間(N0からN7)、そしてその後にようやくループを、修正モードか進化モードで。正常化の区間まるごと、機能の最初の一行に触れる前に。このページとコースのマニュアル、パート2。

混同されないよう名指ししておく、外に残るもの:技術の移行(プラットフォームの変更、言語の変更、データベースの変更)は方法のユースケースではない。それは別のプロジェクトであり、一般には第0段の排除基準に当たる Ref. 46。受け継ぐシステムにアクセス可能なリポジトリがないか、その画面をプログラムから操作できず操作可能にもできないなら、相応しいのはそれを正常化することではなく、第0段を丸ごと通した、それを置き換える新規プロジェクトだ。

そして三番目のケースに当てはまる一言:レガシーが他のチームのものか自分のものかは同じことだ。三か月前にモデルと一緒に証拠なしで構築したシステムは、三年前に請負業者が作ったものとまったく同じだけレガシーだ。変わるのは読む労力であって、道ではない。

原則:書き直さずに正常化する、すべての入力とともに

正常化とは、システムを、方法がループを開くときに前提としている状態まで持っていくことだ。そしてそれを、私が譲らない三つのルールで行う。

第一:書き直さない。 正常化は機能に触れない。システムの周りに足りないもの(契約、地図、テスト環境、テスト群、繰り返せるデプロイ、既に世界へ作用しているものの上の錠)を置き、システムは以前と同じことをしたままにする。レガシーは、直すべきだったバグよりも「全部片付けよう」という熱意によって壊れることの方が多い。

第二:二つの速度。 負債には、どんな変更よりも前に払う部分があり、それを安全ベルトと呼ぶ:実データに似たデータを持つテスト環境でシステムを走らせられること、繰り返せる形でデプロイできること、秘密をコードの外に置くこと、そしてそのどれかが変わったら赤になる、重要なフローの特性化テスト群を持つこと。安全ベルトは硬いゲートだ:それなしには何も変えない。例外は、本番の緊急のために書かれた一つだけで、後ほど説明する。残りの負債は 触れたときに払う:ブロックがあるモジュールに入るとき、そのモジュールの正常化の保留項目が一緒に入る。決して、始める前の「全体清掃」ではない。

第三:前の段階のすべての入力が存在しなければならない。たとえ自動発見で復元する必要があっても。 これがこの道を「ループを当てるだけ」から区別するルールだ。立ち上げ区間の各段は後続の段が読む成果物を生む:初期調査、適格性シート、共働の約束、プロジェクトファイル、セマンティックツリー、ボリュームの調査、サイジング、環境の調査、ゲート。新規プロジェクトではそれらの入力を、オーナーがエージェントとともに取り込みから書く。レガシーでは誰も書いておらず、ループはそれなしには始められない。解決は飛ばすことではない:エージェントが システムそのものから復元することだ。コードを、データベースのスキーマを、各環境の設定を、ログを、あるだけの文書を読み、それらの文書の各主張がどこから出たかの印を帯びるようにする。私が使う印は五つ:[コード]、[データベース]、[設定]、[文書]、[推定]、加えてオーナーが確認または訂正したものには[業務]。印の付いた復元された文書は、コードを読まずに検証できる文書だ:オーナーは[推定]と印された主張を見て確認するか訂正し、[コード]と印されたものを見てシステムが自分の思っている通りのことをしているか確かめる。合わないものは 食い違いであり、食い違いは正常化の金塊だ:誰も報告しなかったバグであり、誰も決めなかったルールだ。

復元される入力の表

抽象のままにならないよう、立ち上げ区間の各入力と、新規プロジェクトではそれがどこで生まれ、進化・修正の道ではどう手に入れるかを並べておく。

入力新規プロジェクトでは誰が作るか進化・修正の道では誰が確認するか
docs/INITIAL_SURVEY.mdオーナーが、手で、取り込みで(第0段と第2段)。エージェントがN2でコード、データベース、設定から出所の印付きで起草する。オーナーは業務だけが知ることを足す。オーナーが、[推定]の部分を主張ごとに。
docs/ELIGIBILITY_CRITERIA.md と docs/ELIGIBILITY.md第0段。N0、レガシー固有の四つの基準を加えて。オーナーが決める。
docs/WORKING_AGREEMENT.md第1段。N1、レガシー固有の五つのルールを加えて。オーナー。
PROJECT.md、docs/SEMANTIC_TREE.md、docs/STATUS.md第2段、調査から。N2、システムから、印付きで。加えて食い違いの一覧。オーナーがツリーを辿り、食い違いを一つずつ決める。
docs/AUDIT_[fecha].md第13段、最後に。N3、最初に:負債の棚卸しだ。オーナーが読み、二つの発見を検証する。
docs/ENVIRONMENTS_SURVEY.md、テスト環境、継続的インテグレーション、繰り返せるデプロイ、docs/GATES.md第4段と第15段。N4、安全ベルト、特性化テスト群とともに。オーナーがスクリーンショットとデプロイの二度目の実行を見る。
docs/CONSEQUENTIAL_ACTIONS_SURVEY.md、docs/PRODUCER_CONSUMER_MAP.md第14段と第11段。N5、コードとデータベースの棚卸しによって。オーナーが錠を一つずつ確認する。
docs/VOLUME_SURVEY.md、docs/SIZING.md第3段、業務が出す数字で。N6、データベースとログで計測した数字で(サイジングに適用した第7段)。オーナーは計測できないものだけを提供する。
docs/PENDING.md第5段、顧客の依頼から。N7、監査、食い違い、顧客の依頼から、「ブロックする/触れたときに払う/待てる」の印付きで。オーナーが順序を決める。
docs/DECISIONS.md、docs/GOTCHAS.md、docs/LOCKS.md、docs/DEPLOYMENT.md第6、8、12、13段。空で作られるか、N2、N4、N5で埋められ、新規プロジェクトと同じようにループの中で育つ。オーナー。

N7を終えてこれらのファイルのどれかが欠けていたら、区間は登れていない。システムが「動いている」かどうかは関係ない:ループは最初のセッションでそれを必要とする。

正常化の区間:八つのステーション

はしごの二十四と混同されないよう、これらを段ではなくステーションと呼び、N0からN7と番号を振る。新しい段ではない:立ち上げの段と運用の三つ(第11段、第13段、第14段)を、別の順序と別の入口で並べたものだ。新規プロジェクトでは入口が調査であり、ここでは入口がシステムで、読むのはエージェントだ。

ステーション由来する段新規プロジェクトとの違い
N0 — 既存システムの適格性0基準が四つ多い。X2は画面ごとに測る。赤なら、それは条件ではなく最初の保留項目だ。
N1 — レガシーのための共働の約束1ルールが五つ多い:頼まれていないリファクタリングをしない、触れる前に読む、ついでに直さず書き留める、現在の挙動が仕様である、特性化が緑でなければ何も入らない。
N2 — システムの読み取り2調査、プロジェクトファイル、ツリーが、出所の印付きでコードから出てくる。食い違いの一覧が現れる。
N3 — 棚卸しとしての監査11最後ではなく最初に行き、各発見がブロックするか、触れたときに払うか、待てるかを言う。
N4 — 安全ベルト4、7、13データ付きのテスト環境、繰り返せるデプロイ、外に出した秘密、継続的インテグレーション、そして特性化テスト群。硬いゲート。
N5 — コードからの錠と地図12、8何も変える前に、世界へ作用するすべてと、部分と部分のあいだのすべての契約を棚卸しする。
N6 — 実数でサイジングする3、9一次の数字は聞くのではなく測る。オーナーはデータベースにないものだけを提供する。
N7 — 正常化のバックログ5負債と顧客の依頼を一つのキューに、速度の印とモジュールごとの対付きで。

順序が重要だ。N3がN4より前なのは、監査が安全ベルトに何が入るべきかを言うからだ(見つけた秘密、操作できない画面、繰り返せないデプロイ)。N5が安全ベルトの後なのは、帰結のある行動を棚卸しするには、間違えても高くつかない場所でシステムを走らせられる必要があるからだ。N6が最後なのは、N4でようやく存在するデータ付きのテスト環境の上で測るからだ。そしてN7が締めるのは、それ以前のすべてを一つのキューにまとめるからだ。

正常化の順序

期限はない:各段階はシステムが求めるだけ続き、唯一決まっているのは順序だ。

段階ステーションほかに何が起きるか
1N0、N1、N2、N3オーナーを隣に置いてシステムを読む。ノードを確認し、食い違いを決める。何も変えない。段階の締めに:復元された地図と負債の棚卸し。
2N4、N5安全ベルト:データ付きのテスト環境、二度繰り返したデプロイ、ローテーションした秘密、重要なフローの特性化テスト群。既に作用しているものの上の錠を確認。締めに:システムがテスト環境で動き、テスト群が緑。
3N6、N7、そして最初のブロック計測したサイジング。順序の付いたバックログ。第5段で最初のブロックを開く。修正か進化か、正常化の保留項目を対にして。ここから先はいつものループだ。

システムが大きければ、育つのは段階1(読むものが多い)と段階2の特性化テスト群(フローが多い)だ。N7は育たない:一度に座って書けない正常化のバックログは、誰も維持しないバックログだ。


N0 — 既存システムの適格性:モデルが検証できる前提条件

プロンプトを送る前に、これが存在しなければならず、作るのはあなた(またはあなたと業務)であってエージェントではありません:

  • docs/INITIAL_SURVEY.md、初日に書ける短い版:業務によればシステムは何をして誰のためか、今日何が痛むか(依頼のきっかけとなったバグ、足りないもの)、誰が作ったか、その人はつかまるか、どこで動いているか、誰が何にアクセスできるか、バックアップはあるか誰が取るか。半ページ、意図的に不完全に:N2でエージェントがシステムから完成させます。
  • docs/ELIGIBILITY_CRITERIA.md:第0段のシート(X1、X2と重み付けのもの)に、上のレガシーの七つの前提条件を加えたもの。それぞれに空の三列を:緑か赤か、証拠(エージェントがそれを検証するために何をしたか)、そして赤なら前段のプロジェクト。
  • エージェントのためのリポジトリへの読み取りアクセス、データの複製(または読み取り専用の本番)へのアクセス、そして環境を立ち上げようと試せる場所。認証情報はチャットの外に。これがなければ前提条件1、5、6は検証できず、赤のままになります。
  • 受け入れられる最低限の状態:エージェントがリポジトリをクローンでき、システムを立ち上げようと試せる場所があること。

最初の:

We are going to assess whether this existing system can be taken over with the Urazuke method, with prerequisites that you verify by doing, not by asking. Read the initial survey in docs/INITIAL_SURVEY.md and the criteria sheet in docs/ELIGIBILITY_CRITERIA.md. Then, changing nothing in the system, verify each prerequisite with evidence: (1) try to set up a complete environment of the system from the repository and a copy of the data, with its sources, data model and persistence, and tell me exactly what you could and could not bring up; (2) read the whole code and tell me whether you can understand and work with it, module by module, naming what you cannot understand; (3) from the code alone, write docs/FUNCTIONALITY_RECOVERED.md: the complete functionality of the system described for an end user, screen by screen and process by process, marking what you inferred; (4) list every screen and say whether it can be driven by a test tool with each element accessible and the backend effect checkable, and prove it by writing and running one end-to-end test of one flow; (5) try to build and run the system from the sources with today's tools and report every dependency that does not resolve; (6) check whether the production data can be copied and anonymized into a test environment and whether a backup exists and has ever been restored; (7) list every external integration and say whether it has a test mode or can be isolated at the edge. For each prerequisite: green or red, the evidence (what you did and what happened), and, if red, what project would make it green. Do not decide: present me the sheet, and I decide. Reply in my language.

何を求めているか:前提条件が実際に行うことで検証されること(立ち上げる、読む、文書を書く、テストを走らせる)。フロンティアのモデルはその四つができるのであり、そうすれば適格性は意見ではなくなるからだ。回復された機能の文書。コードが取り組み可能であることの最も強い証明であり、しかもN2が地図に変えるものの最初の草稿でもある。そして各赤がそれを緑にするプロジェクトとともに来ること。足りない前提条件は拒絶ではなく、独自の範囲を持つ前段の作業だからだ。

プロンプトを送る前に(締めのプロンプト):各前提条件の証拠とともにシートを読んだ後の、一行のあなたの決定。そして各赤について、前段のプロジェクトを今やるか、後でやるか、決してやらないか(そのときシステムは適格ではありません)というあなたの決定。

締めの:

Decision: [go / go after these prerequisite projects: … / no-go]. Write the final sheet to docs/ELIGIBILITY.md with the date, who decided, each prerequisite with its colour and its evidence, and, for every red one, the prerequisite project as a pending item in docs/PENDING.md marked as blocking, with its own acceptance criterion: the prerequisite verified green. Include the questions you asked and my answers.

完全性の検証:各前提条件に、あなたの答えではなくエージェントが行ったことの証拠があるか? docs/FUNCTIONALITY_RECOVERED.md は存在し、あなたはオーナーとしてそれを読んだか:彼が持っていると思っているシステムを記述しているか? 一つのフローの本物のエンドツーエンドのテストを走らせたか? 各赤に出口の基準を持つ前段のプロジェクトがあるか? 警告サイン:誰も理解していないシステムについて、一日ですべてが緑。エージェントは行う代わりに答えた。


N1 — レガシーのための共働の約束

プロンプトを送る前に、これを手元に持っていなければなりません:

  • あなたの働き方の好み、第1段と同じく短い一覧で:言語、どれだけ質問してほしいか、どんな自律を与えるか、何は許容しないか。
  • 正常化のあいだに受け入れるリスクの水準についてのあなたの決定:エージェントが自分でテスト環境にデプロイしてよいかどうか(本番へは、N4が閉じて第15段を登るまで、決して)。
  • docs/ELIGIBILITY.md(N0)、締め済み。
  • 受け入れられる最低限の状態:第1段の質問とリスクの質問に答えられます。

最初の:

Before we touch anything, we are going to set the working agreement between you and me for a system that already exists and has users. Write docs/WORKING_AGREEMENT.md with the six rules of the method (my time is sacred; zero technical debt; exact scope; documentation in the same commit; never report as done what you have not verified; speak my language), each with one line explaining what it prevents, and these five rules for an inherited system: (7) Nothing is refactored that was not asked for, and no module is rewritten. (8) Code you do not understand is read before it is touched, and what you learn goes into the system map. (9) Anything strange you find (a secret in the code, a dead path, a duplicated rule, a query without an index) is logged as a pending item with its evidence, never fixed in passing. (10) Current behaviour is the specification until the owner says otherwise: a difference between what the code does and what the business says is a discrepancy for me to decide, not a bug for you to fix silently. (11) No change reaches the test environment without the characterization suite green. Add any rules you think this system needs, marked as proposals. If you need to know something about how I work in order to write this, ask me.

求めているのは、いつもの六つのルールと、他人のコードを前にしたモデルが反射的に三つのことをするから存在する五つだ:並べ替える。悪いと思ったところを「直す」。そして、コードがすることが自分の期待と違えばそれは誤りだと決めてかかる。ルール7、9、10はまさにその三つの反射を塞ぐ。ルール8は読むことを地図に変える。エージェントがあるモジュールについて学んだことがセッションを閉じたときに失われないように。ルール11は安全ベルトをルールとして書いたもので、テスト群が存在する前にルールが存在するようにするためだ。

締めの: 第1段の締めのプロンプトを変更なしで。提案を理由付きで受け入れたり却下したりして、約束は日付と版とともに残る。

警告サイン:エージェントが「触れるにつれてコードを現代化する」をルールとして提案する。そのルールは変装した書き直しだ。書かれた理由とともに却下すること。


N2 — システムの読み取り:復元された地図と食い違い

プロンプトを送る前に、これが存在しなければならず、作るのはあなた(またはあなたと業務)であってエージェントではありません:

  • 読めるものすべてへのエージェントの読み取りアクセス:リポジトリ全体(主ブランチだけでなくすべてのブランチ)、データベースのスキーマ(読み取り専用の認証情報、チャットの外に)、各環境の設定(秘密の値を伏せた環境ファイル、または値のない変数の一覧)、あれば最近のログ、そして古いメールでも時代遅れのマニュアルでもいいので何らかの文書。
  • N0の docs/INITIAL_SURVEY.md に、あなたがオーナーと書く新しい節:業務がシステムはこうすると信じていることを、業務の言葉で、ユースケースごとに。そして覚えているルール(「予約は二時間前を切ったらキャンセルできない」)。それをシステムと照合しないでください:まさにその比較をエージェントがするのであり、違いが食い違いです。
  • docs/WORKING_AGREEMENT.md(N1)、締め済み。
  • リポジトリの外に住んでいてシステムに触れるもののあなたが書いた一覧:ロボット、データベースを読む表計算、サーバーに仕込まれた定期処理、あるテーブルを消費する別のシステム。エージェントはコードからそれを見ることができません。
  • 受け入れられる最低限の状態:エージェントがコードとデータベースのスキーマを読めて、調査に業務の言葉によるユースケースが三つとルールが三つ以上あります。

最初の:

We are going to recover the map of this system from what exists. Read the whole repository (every branch), the database schema (read-only), the configuration of each environment, the recent logs and whatever documentation there is; if some part cannot be read from where you are, tell me and mark it as a gap; do not fill it by guessing. Then write three things. First, complete docs/INITIAL_SURVEY.md in the form the method expects (what the system does and for whom; what it does NOT do; who uses it; the technology; the environments; what an error costs), with every statement tagged by its source: [code], [database], [configuration], [documentation], [business] for what the survey already says, or [inferred]. Second, PROJECT.md, three hundred lines at most, and docs/SEMANTIC_TREE.md: the domains and, under each one, the actors, the processes (each with trigger, steps, outcome and exceptions as the code actually implements them), the entities with the attributes, states and transitions the database and the code enforce, the screens, the external integrations and the scheduled jobs; every node tagged the same way. Third, docs/DISCREPANCIES.md: everything where the code, the database, the documentation and what the business says in the survey do not agree, with the evidence on each side. Do not resolve any discrepancy and do not fix anything: list them. Create docs/STATUS.md for the living state. Reply in my language.

求めているのは、すべてを読んで読めなかったものを申告すること(完全性の条項のレガシー版:穴は印すのであって埋めるのではない)。調査とツリーが各主張に出所の印付きで出てくること。その印こそがコードを読まずに検証することを可能にするからだ。プロセスと状態が、あるべき姿ではなくコードが実装しているものであること。現在の挙動が仕様だからだ(約束のルール10)。定期処理を含めること。誰も覚えておらず、最も害をなすものだからだ。そして食い違いがそれぞれの側の証拠とともに、解決されずに列挙されること。解決することは決めることであり、決めるのはあなたの仕事だからだ。

プロンプトを送る前に(締めのプロンプト):オーナーとノードを一つずつ辿ったツリー、確認されたノードの一覧と訂正されたノードの一覧。そして食い違いの一覧、それぞれオーナーの決定を一行と日付付きで(システムが正しくて業務が忘れていた。システムが間違っていて変える。または日付付きで開いたまま、ただし多すぎないように)。

締めの:

I confirm these nodes: [list]. Correct these: [list]. The discrepancies are decided as follows: [one line each: discrepancy, my decision, today's date]. Finalize docs/INITIAL_SURVEY.md, PROJECT.md and docs/SEMANTIC_TREE.md with today's date, keeping the source tags. Write each discrepancy decision in docs/DECISIONS.md with my exact words, and open a pending item in docs/PENDING.md for every discrepancy where I decided the system must change; for the ones where I decided the current behaviour stays, write it next to the node as a confirmed rule. Add to PROJECT.md the instruction to read this file, the tree and the working agreement at the start of every session.

求めているのは、各食い違いについての決定がいつもの三つの場所(決定の記録、変える必要があれば保留項目、確認されたならツリー)に残ること。そして締めるときに出所の印が消されないこと:印を失ったツリーは、もう検証できないツリーだ。

完全性の検証:オーナーとしてツリーを辿ること。業務が一度も使わなかったエンティティの状態はあるか? [コード]と印されているなら、誰も使っていなくてもシステムはそれを持っており、それは食い違いだ。ツリーに定期処理はあるか? 一つもないなら、エージェントにどこを探したか聞くこと。各食い違いに日付付きの決定はあるか? 第2段の読み取りテストを通ったか(新しいセッションがシステムは何を*しない*か知っている)? 警告サイン:ツリーに[推定]と印されたものが一つもない(エージェントは読んだものと推測したものを区別していない)。食い違いの一覧が空だ(レガシーで空になることは決してない:エージェントは比較を誤ったか、比較しなかった)。プロジェクトファイルが「文書化することが多かったから」三百行を超える(それはツリーへ行き、起きたことは生きた状態へ行く Ref. 41)。


N3 — 負債の棚卸しとしての監査

プロンプトを送る前に、これが存在しなければならず、作るのはあなた(またはあなたと業務)であってエージェントではありません:

  • ツールが許すなら、エージェントの新しいセッション。きれいなクローンと「あなたは監査人です。このシステムを読んだこともなく、触れることもありません」と書いた指示ファイル付きで。N2のセッションの前提を共有しないためです。できないなら同じセッションで、ただしそれを承知の上で。
  • システムが動いている環境(データベース、ログ、設定)への読み取り専用アクセス、読み取り専用の認証情報はチャットの外に。
  • N2の復元された地図(PROJECT.md、docs/SEMANTIC_TREE.md)と docs/DISCREPANCIES.md。監査人が既に書かれていることを再発見しないためです。
  • 「ブロックする」が何を意味するかについてのあなたの基準:一般には、露出した秘密、プログラムから操作できない画面、繰り返せないデプロイ、バックアップの不在、そしてデータを損なうか過剰に請求しうるもの。渡せるように二行で書いておくこと。
  • 受け入れられる最低限の状態:監査人は読み取り専用を持ち、あなたが何をブロックすると考えているかを知っています。

最初の:

Audit this system for integrity, security, performance, code quality and deployability, as the inventory of what must be normalized before and during its evolution. Read-only: change nothing except writing your report to docs/AUDIT_[date].md. If auditing some part requires access you lack (the database, the logs, the server), tell me and mark that part as not audited; do not pass it as fine. Go through all of the code, not a sample, and read docs/SEMANTIC_TREE.md and docs/DISCREPANCIES.md first so that you do not report what is already known. For every finding: where it is (file and line), the risk, the evidence that proves it (the command, the query, the number), its priority (P0 must be fixed now, P1 soon, P2 when possible), and one more field: whether it BLOCKS (must be fixed before any change, by my criteria: [criteria]), whether it is PAID WHEN TOUCHED (fixed together with the first change that enters its module), or whether it CAN WAIT. Grade every dimension you audited. End with every finding turned into a proposed pending item, blocking ones first. Reply in my language.

求めているのは、第13段の監査に「デプロイ可能性」の次元を加えたもの(レガシーではデプロイが最初の問題であることが多いから)と、速度の項目だ。それが報告書を計画に変える:その項目がなければ、監査されたレガシーには四十の発見があり、どれから始めるか誰も分からない。何がブロックするかの基準は監査人ではなく私が与える。業務上の帰結に依存するからだ。

締めの: 第13段の締めのプロンプトを、構築者に、一つ付け加えて:開く保留項目は発見の速度の印を帯びる。

検証:報告書は何を監査*できなかった*かを言っているか? 「ブロックする」と印された発見が少なくとも一つあるか?(レガシーには常にある。なければ、監査人は秘密もデプロイも見ていない。)無作為に選んだ二つの発見に、ファイル、行、再現できる証拠はあるか? 警告サイン:すべてが「待てる」にある。それは迷惑をかけたくない監査人だ。


N4 — 安全ベルト

プロンプトを送る前に、これが存在しなければならず、作るのはあなた(またはあなたと業務)であってエージェントではありません:

  • docs/ENVIRONMENTS_SURVEY.md。エージェントがN2で印付きで起草し、あなたが完成させたもの:今日どこで動いているか、今日どうデプロイしているか(「FTPでファイルをコピーしている」でも構いません)、秘密はサーバーのどこに住むことになるか、誰がアクセスを持つか、そしてテスト環境はどこで動くことになるか(別のサーバー、コンテナ、クラウドのアカウント。何もなければそう言えばエージェントが最も単純なものを提案します)。プロンプトはそれを「the environments survey」と呼びます。どこにあるか伝えてください。
  • 本番サーバーへのエージェントの読み取り専用アクセス(データベースと設定をコピーするため)と、テスト環境が動く場所への書き込み権限。認証情報はチャットの外に。
  • テストデータの匿名化についてのあなたの決定:どの項目が個人データか(氏名、電話、メール、身分証)、どう置き換えるか。法律上の義務であって技術的な好みではないので、決めるのはあなたです。
  • 特性化のための重要なフローの一覧。セマンティックツリーのプロセスをもとにあなたが書くもの:意図せず変わったら、業務にお金か信頼を失わせるもの。小さいシステムで四つから八つ。「全部」ではありません:全部はゼロと同じです。
  • docs/AUDIT_[fecha].md(N3)。エージェントがどんな秘密を見つけ、どの画面が操作できないかを知るために。
  • 少なくとも一度復元された本番のバックアップ。あなたのマシンの上でも構いません。エージェントがサーバーに触れる前に。N0の条件がここで期限を迎えます。
  • 受け入れられる最低限の状態:テスト環境がどこで動くか分かっていて、重要なフローの一覧があり、匿名化を決め、バックアップを復元しました。

環境、デプロイ、秘密のための:

We are going to build the safety belt around this system before changing anything in it. Read the environments survey, docs/AUDIT_[date].md and docs/SEMANTIC_TREE.md. Evaluate whether you have what is needed (read access to the server where it runs and to its database, write access to where the test environment will run, the way it is deployed today); if anything is missing, ask me before starting. Then set up, without touching any functionality: (1) a test environment that runs the system exactly as production does, with a copy of the data where the personal fields I listed are anonymized; (2) a reproducible deployment to that environment, run twice, showing me that the second run changed nothing; (3) every secret found in the repository or in the code moved to the server configuration (environment file or vault), with the list of what you moved so that I rotate each one; (4) continuous integration running whatever test suite exists today, even if it is a single smoke test, on every push; (5) docs/GATES.md with the gates of this project, including: nothing reaches the test environment without the characterization suite green, and nothing reaches production without the full suite green with the exact version. Document all of it in docs/DEPLOYMENT.md so that a person can do it by hand without you. Take a screenshot of the system running in the test environment and show it to me. Reply in my language.

求めているのは、既に存在するものの周りに築く第4段の骨組みだ。第15段の半分を前倒しして(秘密を外へ、デプロイを文書化)。レガシーではコードの中の秘密が例外ではなく規則だからだ Ref. 42。匿名化を細部ではなく環境の一部として。そしてテスト群が存在する前にゲートを書いて、テスト群が生まれたときから既にゲートであるように。

プロンプトを送る前に(テスト群のプロンプト):匿名化されたデータとともにあなたが開いたテスト環境。一覧の秘密を今日ローテーションしたこと。プロンプトの穴のための重要なフローの一覧。そしてN0が赤の画面を残していたなら、それを操作可能にするブロックする保留項目を、このテスト群の前か一部として閉じておくこと。

特性化テスト群のための:

We are going to write the characterization tests of these critical flows: [list]. A characterization test captures what the system does today, exactly as it does it, defects included; it is not a test of what the system should do. For each flow: drive it from the screen as a user would and check the effect in the backend (the row, the state, the message queued). Every test must pass against the current code. Then prove that each test actually watches its flow: break the flow deliberately with a temporary change, show me the red output, revert the change, show me the green. If a flow cannot be driven from the screen, do not simulate it: say so and open a pending item marked as blocking. If while writing these tests you find behaviour that looks wrong, do not fix it: add it to docs/DISCREPANCIES.md with the evidence. Record the command to run the suite in docs/STATUS.md, and make the suite the gate for the test environment as docs/GATES.md says. Reply in my language.

求めているのは、第8段を裏返したものだ。新規プロジェクトではテストは赤で生まれ、変更とともに緑になる。ここではテストは緑で生まれる。あるものを捉えるからだ。そして役に立つことの証明は、 わざとフローを壊したときに赤になることだ。そのミューテーションの実証がなければ、特性化テストは何も見ていないから通るテストであり、それはバグを隠す緑と同じ問題だ Ref. 44。そして二つの規律の条項:操作できないものは申告されブロックする。悪く見えるものは食い違いとして書き留められ、直されない。オーナーが決めるまでは、現在の挙動が仕様だからだ。

完全性の検証:あなた自身がテスト環境のURLを開いて、データの入ったシステムを見たか? そのデータの中で本物の名前を探して、なかったか? デプロイは二度走り、二度目は何も変えなかったか?リポジトリでの秘密の検索を求めて、空で返ってきたか? 一覧の秘密をそれぞれローテーションしたか? 各重要なフローに自分のテストがあり、各テストにミューテーションによる赤が見えているか? 警告サイン:特性化テスト群が「一発で」全部通り、赤が一度も示されなかった。テスト環境が「エージェントのマシンの中」で動いていて、あなたが開ける場所ではない。テストデータが匿名化されたコピーではなく「いくつかの見本のレコード」だ(レガシーのバグは実データの中に住んでいて、見本のデータの中にはいない)。


N5 — コードからの錠と生産者・消費者の地図

プロンプトを送る前に、これが存在しなければならず、作るのはあなた(またはあなたと業務)であってエージェントではありません:

  • オーナーとともに、システムが外へ向けてすると業務が知っていることの書かれた一覧:何を請求するか、何を送るか、誰に知らせるか、何を削除するか、何が独りで走るか。 docs/INITIAL_SURVEY.md の一節に入ります。エージェントは業務が覚えているより多くのものをコードの中に見つけます。二つの一覧の比較が結果です。
  • サーバーの定期処理(定期タスクの一覧、またはあなたのプラットフォームの同等物)へのエージェントのアクセス。自動の送信はコードではなくそこに住んでいることが多いからです。
  • リポジトリの外に住むものの一覧(N2)、地図のために。
  • N4のテスト環境が動いていること。実際の帰結なしに行動を発火させて何が起きるか見られるように。
  • 受け入れられる最低限の状態:業務が自分の一覧を書き、エージェントが定期タスクを見られます。

最初の:

Go through the code, the database triggers and the scheduled jobs of the server looking for everything that charges, sends, approves, deletes, notifies outwards or runs on a schedule, and write docs/CONSEQUENTIAL_ACTIONS_SURVEY.md with every statement tagged by its source. Compare it with the list the business wrote in docs/INITIAL_SURVEY.md: whatever the code does that the business did not list, or the other way round, ask me about before going on. For every action: what triggers it, whether it can run twice, whether it is reversible, what lock exists today if any, and what the way back is. In the same pass, build docs/PRODUCER_CONSUMER_MAP.md: for every contract in the system (a service, a table, a file format, a list of values), who produces it and who consumes it, including the things outside the repository I told you about. If there are parts you cannot see, say so instead of leaving them out. Present me the actions table with a proposed lock for each (explicit confirmation, double safety, dry-run mode, daily limit, a human in the loop) and a proposal of which locks go NOW, before any change, and which can go when the module is touched. Do not implement anything yet: I confirm lock by lock. Reply in my language.

求めているのは、第14段と第11段の棚卸しを一周で行うことだ。同じコードを辿るからだ。業務が覚えていることとコードがすることの比較、そこに誰も覚えていなかった送信が現れる。そして各錠についての今か、触れたときかの提案、それは二つの速度のルールを保護に当てはめたものだ:請求する行動の上の錠は今行く。月次の書き出しの上の錠は、そのモジュールに触れるブロックまで待てる。

締めの: 第14段の締めのプロンプトを、「今」と印された錠とともに。それぞれ錠のないバージョンに対する赤のテスト付きで。残りは印とともにバックログに残る。

警告サイン:エージェントが業務の列挙したのとまったく同じ行動を見つけた。レガシーでそんなことは決してない。定期タスクかデータベースのトリガを見ていない。


N6 — 実数でサイジングする

プロンプトを送る前に、これを手元に持っていなければなりません:

  • 本番データベース(または、匿名化が日付も数量も触っていないなら、N4の完全なコピー)とアクセスまたはアプリケーションのログへの読み取り専用アクセス。認証情報はチャットの外に。
  • 業務だけが持つ二つの答えを書いたもの:今後二年でどれだけ成長すると見込むか、そしてシステムが一か所より多くで使われるか(「十倍」)。
  • 各計器のテストのための既知の事例:例えば、あなたが手で数えられる小さいテーブルのレコード数。
  • 受け入れられる最低限の状態:エージェントがデータベースを参照でき、あなたは二つの答えを持っています。

最初の:

Before changing anything we are going to size this system with its real numbers. With read-only access to the production database (or the complete test copy) and to the logs, measure instead of asking: rows per table and growth per month from the timestamps, events per entity, peak concurrency from the access logs, data size today and projected at five years, and the slowest queries. Write a meter for each number (a script that lives in the repository, with a test against a known case I will give you) and show me every number together with the command that produces it; audit each meter in both directions (is everything that should be counted, counted? does everything counted exist?). Write docs/VOLUME_SURVEY.md with every figure tagged [database] or [log], and ask me only for what cannot be measured: the growth the business expects and whether the system will serve more than one site. Then write docs/SIZING.md: what breaks first if everything is multiplied by ten, which of the current architecture choices hold and which do not, and which asymmetric decisions we take now, before evolving, because they are cheap today and expensive later. Do not change any code. Reply in my language.

求めているのは、聞く代わりに計測することだ。それはレガシーが許し、新規プロジェクトが許さないことだ。テスト付きの計器と第7段の二方向の監査。計器は嘘をつくからだ Ref. 35、Ref. 36。そして進化の前のゲートとしてのサイジング Ref. 14:現在のアーキテクチャが「十倍」に耐えず、顧客の依頼がまさに成長することなら、それは三番目のブロックではなく今分かる。

締めの: 第3段の締めのプロンプトを、耐えないものについて提案された選択肢から選ぶか、現在のもので耐えると確認して。

警告サイン:近似と印されていない「おおよそ」の数字。データベースにあるなら測る。なければ聞く。三つ目の選択肢はない。


N7 — 顧客の依頼と対にした正常化のバックログ

プロンプトを送る前に、これが存在しなければならず、作るのはあなた(またはあなたと業務)であってエージェントではありません:

  • この段階に対する顧客の依頼を、散文で、顧客の言葉で、二つの一覧に分けて:今日失敗していること(それぞれ、業務によればどう再現するか、何が起きるか、何が起きるべきか)と、 足りないこと(新しいもの)。docs/blocks/STAGE_01_REQUEST.md でも好きな場所でも構いません。プロンプトは「the client's request for this stage」と言うので、どこにあるか伝えてください。オーナーが優先順位を出したなら、それも。
  • N2からN6までのすべての成果物が締め済みであること:ツリー、監査、決定済みの食い違い、錠、サイジング。どれかが欠けているならこのプロンプトを開かないでください:バックログが不完全に出てきて、何が足りないのか分からなくなります。
  • 既に存在するブロックする保留項目(N0、N3、N4のもの)が閉じているか、日付付きで進行中であること。
  • 受け入れられる最低限の状態:顧客の依頼がその言葉で二つの一覧になっていて、前のステーションの成果物が存在します。

最初の:

We are going to turn the normalization and the client's request for this stage into one queue of numbered pending items in docs/PENDING.md, each with its full specification as the method asks (number, title, node of the semantic tree, origin, description, business rules with decision and date or marked as missing, data in and out, screens, edge cases, acceptance criteria as given, when, then, how it will be verified, status). Sources for the normalization items: docs/AUDIT_[date].md, the discrepancies I decided to change, the screens that cannot be driven by a program, the secrets to rotate, the locks that are not implemented yet, and the decisions in docs/SIZING.md; each one keeps its speed mark: BLOCKS, PAID WHEN TOUCHED, or CAN WAIT. Sources for the client's items: the client's request for this stage; each one marked CORRECTIVE (something that fails today, with the way to reproduce it in the client's words) or EVOLUTIVE (something new). For every client item, list the normalization items that touch the same modules and should be paid together with it. If the request is ambiguous on any point such that you cannot write a verifiable item, ask me; do not resolve it by assuming. Order: blocking items first, then the client's items in the priority I gave you, each with its paired normalization. Reply in my language.

求めているのは、完全な第5段(詳細な仕様は各保留項目の中に住む。正常化のものにも)に、この道を成り立たせる二つの印を加えたものだ。速度は各負債をいつ払うかを言い、種類はどう閉じるかを言う(修正は失敗を再現するテストで閉じ、進化は第8段のテストで閉じる)。そしてモジュールごとの対、これは「触れたときに払う」のルールを運用可能にしたものだ:「手付金」のブロックを開くとき、支払いモジュールの正常化の保留項目が一緒に入り、それより前でも後でもない。

締めの: 第5段の各セッションのルーチンを、変更なしで、共働の約束の中に。

完全性の検証:「ブロックする」が開いたまま残っているか? ならば最初のブロックは開かない。各修正は顧客の言葉で再現の仕方を言っているか? 顧客の各保留項目には、たとえ空でも対の一覧があるか? 警告サイン:バックログに「待てる」の正常化の保留項目が五十を超えている。それは記録された負債ではない:一覧に変装した書き直しだ。決して払われないものは保管庫へ送って、そう言うこと。


受け継いだシステムの上のループ:修正モードと進化モード

N7を終えると、道ははしごと合流する:第5段から第12段を保留項目ごとに登る。新規プロジェクトと同じく、同じ契約と同じプロンプトで。だが一節を割く価値のある二つの機微がある。それは「方法でレガシーに触れる」を「注意深くレガシーに触れる」から区別するものだからだ。

修正モード:赤は自然なもの

修正の保留項目はバグだ:今日失敗していて、顧客がそれを知っている。新規プロジェクトの第8段では赤は作り出される(テストを書き、古いコードに対して走らせ、失敗するのを見る)。修正では赤はバグそのものだ:失敗を再現するテストを、報告したユーザーのように画面からフローを操作して書き、それが現在のコードに対して失敗しなければならない。失敗しないなら、報告されたバグを再現していない。別のものを再現したのだ。その赤は正しいものを直していることの証明であり、「起きているに違いないこと」についてのエージェントのどんな説明よりも価値がある。根本原因まで四ラウンドかかった事例 Ref. 22 が、書かれた再現なしには各ラウンドが別々の症状を直すのだと私に教えた。

プロンプトを送る前に、これを手元に持っていなければなりません:

  • docs/PENDING.md(N7)の中の修正の保留項目。顧客の言葉による再現の仕方付きで:何をして、何が起きて、何を期待していたか。顧客が再現の仕方を知らないなら、まず事例(レコード、日付、スクリーンショット)を手に入れること。再現なしにテストはなく、テストなしに締めはありません。
  • テスト環境で緑の特性化テスト群(N4)、コマンドは docs/STATUS.md に。
  • これと対になった正常化の保留項目、その保留項目の中に列挙されていること。
  • 決める覚悟:根本原因が、誰も書かなかった業務ルールだったとき(よく起きます)、エージェントは止まって聞いてきます。誰かがその日のうちに答えなければなりません。
  • 受け入れられる最低限の状態:テスト環境で手でバグを再現できます。

修正の保留項目を閉じるための:

This pending item is a correction: [what fails, in the client's words, and how to reproduce it]. Before changing anything: (1) Reproduce the failure with a test that drives the flow from the screen and checks the effect in the backend, and show me that it fails against the current code; that red is the proof that you reproduced the right defect. If you cannot reproduce it, tell me what you tried and what you need; do not fix what you cannot see. (2) Find the root cause and tell me in prose, with the evidence, before fixing. If the root cause is a business rule nobody wrote down, stop and ask me. (3) Fix at the root, not where it hurts, and nothing else: anything else you find goes to a pending item. (4) Show me the test green, the characterization suite still green, and the regression of the neighbouring items. (5) If the fix changes a current behaviour that someone may depend on, say so explicitly: that is a decision for me, not a side effect. Close the paired normalization items of this module in the same block, each with its own evidence. The commit message says "proved red against [version]" and the test counts. Reply in my language.

求めているのは、診断の前の再現だ。モデルは再現していないものをとても自信ありげに診断するからだ。触れる前の散文による根本原因、あなたが的外れな修正を止められるように。根とそれだけ、レガシーでは「ついでだから」が動いていたものを壊す最も多い形だからだ。システム全体の回帰としての緑の特性化。そして条項5、挙動の変更を決定に変えるもの。そして対:このモジュールの負債は「後で」ではなく今、その証拠とともに払われる。

進化モード:特性化が回帰である

進化の保留項目は、存在するものの上の新しい何かだ。第5段のプロンプトで開き、第6段と第8段でそのまま構築し、唯一の違いは「近隣の回帰」が何を意味するかだ:ここでは近隣はシステム全体であり、動いていたものが動き続けていると言うのは特性化テスト群だ。ルールがもう二つ。第一:ブロックがあるモジュールに入るとき、そのモジュールの「触れたときに払う」と印された正常化の保留項目が、自分の証拠とともに一緒に入る。二つの速度のルールだ。第二:新しいものは最初から完全な方法とともに生まれる。つまり、保留項目の中の仕様、赤のテスト、エンドツーエンドの検証、そして世界へ作用するなら錠とともに。レガシーが古いモジュールにしたことを、新しいモジュールにしてはいけない。

例外:本番の緊急

安全ベルトは硬いゲートであり、硬いゲートには書かれた例外が必要だ。書かなければ、夜の十一時に何かが落ちた日に例外が発明されるからだ。例外はこれだ:本番が落ちているかデータを損なっていて、安全ベルトがまだ完成していないなら、損害を止める最小限を、手での戻り道付きで、オーナーに知らせた上で行う。そして同じ日のうちに修正の保留項目を開き、完全なルーチンで閉じる:それを再現する赤のテスト、根本原因、回帰。ループへ戻ってこない緊急の修正は、利息付きで取り立てられる負債だ。

プロンプトを送る前に、これを手元に持っていなければなりません:本当に緊急であることの確認(本番が落ちているかデータを損なっている。「顧客がピリピリしている」ではありません)、知らせたオーナー、そして戻る方法(N0のバックアップか前のバージョン)が手元にあること。

緊急のための:

This is an urgent fix on production: [what is happening]. Do the minimum that stops the damage, on a branch, with the rollback ready before you deploy, and tell me exactly what you changed and what you did not verify. Do not touch anything else. Then, today, open the corrective pending item in docs/PENDING.md with what happened, and we close it with the full routine: the test that reproduces it in red, the root cause, the fix at the root, the characterization suite and the regression green. Reply in my language.

求めているのは、最小限を、戻り道を後ではなく先に用意して、検証していないことの誠実な報告(第12段)とともに。そして同じ日のうちにループへ戻る義務、それが例外を習慣から分けるものだ。

レガシーにおける運用品質の六つの段(16から19、21と22)

主文書の第16段から第19段、第21段と第22段(可観測性とトレーサビリティ、永続化、脆弱性、性能、そして二つの監視)は二つのユースケースに当てはまり、レガシーでは正確な場所を持つ。そのうちのいくつかは、正常化の区間によって仕事の半分がもう済んでいるからだ:

実際のところ、デプロイ前の四つは正常化のもう一つの段階であり、最初の進化のブロックの前に、または依頼の急ぎ具合によってはそれと一緒に行う。そして二つの監視はデプロイとともに組み立てる。

システムが正常化されたと言えるのはいつか

完全にはならないし、それでいい:「触れたときに払う」と印された負債は何か月もかけて、モジュールごとに払われ、「待てる」と印されたものは払われないまま終わることもあり、それは言わなければならない。はっきりした瞬間を持つのは区間の締めで、それは最初のブロックを開くときだ。その一覧がこれだ:

  1. 復元される入力の表のすべての入力が出所の印付きで存在し、オーナーがツリーの[推定]のノードをすべて確認した(N2)。
  2. 各食い違いに日付付きの決定があり、システムを変えるものには保留項目がある(N2)。
  3. 監査が存在し、各発見に速度の印がある(N3)。
  4. 安全ベルトが緑:あなたが開いた、匿名化されたデータを持つテスト環境。二度走ったデプロイ。空の秘密の検索と、見つかったもののローテーション。緑の継続的インテグレーション。各重要なフローについてミューテーションによる赤を実証した、緑の特性化テスト群(N4)。
  5. すべての帰結のある行動に判定があり、「今」と印された錠に赤のテストがある(N5)。
  6. 一次の数字が計器とテストとともに計測されていて、「十倍」が書かれている(N6)。
  7. 「ブロックする」と印された保留項目が一つも開いておらず、顧客の各保留項目に対のものがある(N7)。
  8. 共働の約束にレガシーの五つのルールがあり、新しいセッションが読み取りテストを通る(N1、N2)。

八つが「はい」なら、システムはこの道が要求するところまで正常化されていて、続くのはいつものはしごだ。主文書のフェーズ3と4(本番リリースと運用)はそのまま当てはまる:定期監査、マニュアル(レガシーには存在しないことが多く、第20段であるがままのシステムから生成する)、常駐エージェント、そして数字による振り返り。振り返りにはレガシー固有の質問が一つある:正常化にいくらかかったか、そして「待てる」と印した負債のうち、結局同じだけ高くついたのはどれか。

道全体の警告サイン

練り上げるべき残り 仮説

  1. N0の七つの前提条件は実際に行って検証されるので、較正可能だ:N0を通る各レガシーが証拠付きのシートを残す。足りないのは事例だ:どれだけのレガシーが各前提条件で落ちるのか、そしてそれを緑にする前段のプロジェクトがいくらかかるのか。もはや基準についての仮説ではない。まだ手元にない計算だ。
  2. 特性化テスト群の大きさ:四つから八つのフローは小さいシステムで私にうまくいったものだ。大きいものでは、基準がフローごとなのか、モジュールごとなのか、かかっている金額ごとなのか分からない。
  3. 大きいシステムで正常化がどう分割されるか:読み取り(N2)は丸ごと行うが、安全ベルト(N4)は各モジュールが触れられることになるのに合わせてモジュールごとに組まれ、硬いゲートはシステムごとではなくモジュールごとに硬くなるのだろうと疑っている。試してはいない。
  4. 方法を中途半端に使ってモデルが構築したレガシー(契約はあるがテストはない)はどうなるか:この道を丸ごと辿るのか、近道があるのか。私の直感は、近道はなく、近道こそがまさに誤りだというものだが、直感でしかない。