step-by-step

ステップごとの手順

ユーザーが、慣れている人なら当たり前に思うことを初めて行おうとしています。PAT の作成、ドメインの設定、CI シークレットの接続などです。理論は必要ありません。値がすべて入力済みで、リンクがすべてクリックできる、上からそのまま進められる番号付きリストを求めています。

作成するのはブロックです。引き継ぎメッセージをひとつ、全体をまとめて送信し、その後は待ちます。

ブロック

Now you: <what they are about to do>

<One line: what sits blocked until this is done.>

1. Open <full URL>
2. <Field>: <the exact value to type>
3. <Choice>: <the exact option to pick>. <The trap, if there is one.>
...
N. Test it: <full URL> → <what to click>

<What they see if it worked.> Tell me and I check it.

手順を実行しやすくするポイント：

• 値はすべて具体的に記載します。 Token name: habits-context-sync のように書き、「名前を付けてください」とは書きません。リポジトリ、オーナー、シークレット名はすでにわかっているはずです。環境を調べて記入してください。プレースホルダーは、助けを求めた人に判断を押し戻すことになります。
• リンクはすべて、サイト内で可能な限り深い完全な URL にします。 https://github.com/settings/personal-access-tokens/new のように記載し、「Settings → Developer settings に移動」とは書きません。安定した URL がないページの場合は、安定した URL のページからのクリック手順を示します。
• 問題が起こる手順の中で、落とし穴を明示します。 「Resource owner：ドロップダウンで Habits-Family を選びます。個人アカウントではありません。」ここで誤った選択をしても、かなり後になるまで気づかないことがあります。
• 自動で行われることを伝え、予期しない項目で手が止まらないようにします。 「（Metadata：Read-only は自動で追加されます。）」のように記載します。
• 分岐はリストを分けずに、該当する手順に含めます。 「pending approval と表示された場合は、こちらで承認します：<url>」
• 最後の手順はテストにし、表示されるはずの結果を記載します。

システムではなく、画面に沿って書きます。ユーザーが見ているボタンを、画面上に表示されている名前で記載します。

手順

1. 先にこちらでできることを済ませます

ターミナルからできることは、ブロックを書く前にすべて実行します。残るのは、ブラウザー、ダッシュボード、パスワードが必要な作業です。この残作業をもとに、冒頭の一文を作ります。つまり、ユーザーが操作するまで何も起きない状態になっているものを伝えます。

完了条件： 残っている各手順で、本当に人の操作が必要であること。

2. 実際の手順を確認します

クリック手順は一次情報（ベンダーの最新ドキュメント、またはページそのもの）で確認します。サードパーティ製の UI は名称が変わることがあり、記憶に頼った手順では、存在しないボタンを探させてしまいます。値は環境から取得します。git のリモート、.env、.env.example、.github/workflows/*（secrets.* の参照はすべて、ブロックで設定する値を示しています）を確認します。

現在の UI を確認できない場合は、その旨を伝えて、画面に何が表示されているか尋ねます。各手順は、確認した情報に基づいている必要があります。

完了条件： 各手順に URL と具体的な値があり、最後のテストで何を確認できるかがわかっていること。

3. 道筋を示してから引き継ぎます

手順	送る内容
約30手順以内で、一度で終わる	ブロックをひとつ送ります。番号付きリストが道筋になります。
約30手順を超える、途中で待機が必要、または複数回に分ける必要がある	まず道筋を、各パートを1行ずつ示してから、パート1だけを送ります。

長い手順は区切り目で分割し、手順数で区切らないでください。各パートはひとまとまりの作業とし、確認可能な状態（「トークンが存在する」「シークレットが設定されている」「ワークフローが正常に実行された」など）で終わるようにします。フォーム入力の途中で終わるのは、ちょうど30手順でも不適切な区切り方です。各パートには Now you (2 of 4): wire the secret のように見出しを付け、手順番号は毎回1から振り直します。

その後は待ちます。メッセージは1回につき1パートだけ送り、次のパートは今回のパートが完了するまで保留します。

4. 報告を受け取ります

完了報告でも、エラーでも、説明と異なる画面でも、次のパートに進む前に解決します。画面が説明と合わない場合は、参照元の情報が古くなっています。最新の手順を調べ直してください。

5. 成功を確認します

実行可能な範囲で、最後の確認をこちらでも行います。目標を想定するだけでなく、実際に達成されたことを示します。

シークレット

シークレットは、それを表示するページから、それを使用するフィールドへ直接渡します。このブロックでは：

• 専用の手順を設け、正確な宛先を明記します。シークレット名と設定 URL、.env の行、キーチェーンのエントリーなどです。
• 作成手順に、**「このチャットに貼り付けないでください」**とそのまま記載します。この会話は記録として残りますが、記録はシークレットの保管場所ではありません。
• 一度しか表示されない値は、生成される場所で「今すぐコピーしてください。一度だけ表示されます」と明記します。

正しい値を取得できたことを確認するには、値そのものではなく、プレフィックス、長さ、末尾の 4 文字などの特性を確認します。実行するツールに値を渡す必要がある場合は、値が出力されない方法を使います。たとえば、値の入力を求める gh secret set NAME や read -s を使います。

シークレットがチャットに書き込まれてしまった場合は、そのことをはっきり伝え、取り消して再発行してもらい、新しいシークレットで続けます。