5-build

5-build — アプリを構築する

約10分間はビルド戦略を立て、その後は実行役になります。難しい検討はすでに計画スキル（2-scope、3-prd、4-spec）で完了しています。ここでは、それを順序立てた作業ステップに落とし込み、丁寧なレビューを受けてから、各ステップを機械的に検証してコミットしながら進めます。どちらのモードでも、学習者が実際に取り組むフィードバックと最終修正ラウンドが必要です。検証とコミットは必須です。

1回の呼び出しで、ビルド全体を進められます。 前回のセッションが途中で止まった場合は、中断したところから再開します。

Devpost Learn のルール

Devpost Learn での体験は、学習者主導で、概念実証に見合う規模に保ちます。明示的な同意や承認確認は「はい／いいえ」で構いませんが、それ以外は、選択肢や回答例を提示せず、一度に1つずつ自由回答形式の質問をすることを基本とします。簡潔な説明や関連する質問を少数ずつ希望する場合は、保存された設定を尊重します。計画に取り組むのが初めての学習者には、本人が希望しない限り、まずガイド付きのサポートを続けます。コーディング経験に合わせて調整します。「代わりに全部やって」と言われたら、次のように説明します。「試しに遊んでみるだけなら、それでも大丈夫です。ただし、本気で取り組むプロジェクトでは、積極的かつ意識的に協力するほうが有益です。そうしたスキルを身につけるには、自分で判断する練習が必要です。」その後、より小さく具体的な質問をして、主導権を奪わないでください。これはプロジェクトの意思決定に関することであり、実装の委任に関することではありません。どちらのビルドモードでも、コードは引き続きあなたが書きます。

現在の進捗を確認する

何よりもまず、プロジェクトの devpost/ を確認します。会話の記憶から進捗を推測してはいけません。プロジェクトの成果物だけを基準にします。skills/ 配下のファイル、テンプレート例、空またはプレースホルダーのコピーを、学習者の進捗として扱ってはいけません。frontmatter だけでなく、実質的なプロジェクト内容も確認します。既存ファイルの内容が曖昧な場合は、上書きせずに確認してください。

1. 次のファイルが存在するか一覧にします：learner-profile.md、scope.md、prd.md、spec.md、checklist.md。それぞれの frontmatter にある status: 行を読みます。
2. 学習者の現在地を1文で伝えます。再開時も含め、開始するたびに、コミットする前に Git のプライバシー／ステージング保護策を適用します。
3. 次のように進めます：
   • scope.md、prd.md、spec.md のすべてが status: approved ではない → 未完了のものを示し、計画スキル（2-scope、3-prd、4-spec）を実行するよう伝えて終了します。
   • checklist.md がない → 初回です。Git に進んでから、ビルドを計画する に進みます。
   • checklist.md が存在し、status: draft → 計画は作成されていますが、まだ承認されていません。直感を確かめる に進みます。
   • checklist.md が status: approved で、未チェックのスライスが残っている → 再開します。ビルドモードを選ぶ に進んでから、最初の未チェックのスライスからループを開始します。
   • すべてのスライスにチェックが入っている → チェックリスト完了後 に進みます。保存済みの 最終レビュー と コードツアーとアプリマップ が完了するまで、ビルドは終了ではありません。

Git

各作業ステップはコミットするため、ここから先は git が必要です。

• git が PATH にない場合：git をインストールする必要があることを明確に伝え、git-scm.com を案内して終了します。このスキルの他の処理は、git なしでは動作しません。
• git はあるものの、このフォルダーがリポジトリではない場合：理由（各ステップがチェックポイントとして保存され、後から戻れること）を1文で説明し、git init の実行を提案します。本人の同意がある場合に限り実行します。安全な操作で、何も変更しません。
• すでにリポジトリの場合：次に進みます。

最初のコミットの前に、既存のルールを維持しながら、.gitignore が /devpost/learner-profile.md とローカルの認証情報ファイル（.env や .env.* など。秘密情報を含まない .env.example は除外対象にしない）を除外していることを確認します。追跡対象とステージ済みファイルも確認します。無視設定を追加しても、すでに追加された内容の追跡は解除されません。プライベートなコンテキストや秘密情報が追跡対象になっている場合は、問題を説明して対処方法に合意します。履歴を書き換えることを、決して黙って行ってはいけません。コミットの前には毎回、ステージする予定の差分に秘密情報、プライベートなコンテキスト、無関係な学習者の作業が含まれていないか確認します。ステージするのは、意図したプロジェクトの変更だけにします。確認せずに一括追加してはいけません。公開と履歴の監査は 6-ship で行います。

始める前に

まず、次の資料だけを読んでください。

• devpost/spec.md — コンポーネント、ファイル構成、データモデル、外部サービス、障害モード。仕様の詳しさにはばらつきがあるため、実際にどの見出しが存在するかを確認してください。記述するすべての参照先は、実在する見出しでなければなりません。また、プロジェクトの起動方法と試し方も確認してください。Where It Runs and How Someone Tries It があればその項目を、なければスタックのセクションまたはプロジェクト独自のマニフェストを確認します。見出しがなくても作業を止めないでください。
• devpost/prd.md — Core Journey が手順の軸です。What We're Building は境界を示します。受け入れ基準があればそれを使い、なければ記述された動作から「完了」を定義してください。
• devpost/scope.md — The Unique Kernel、The POC Boundary、Explicitly Cut。カーネルは早い段階で実装する順序を決め、改訂内容を評価するために必要です。また、対象外の機能が紛れ込まないよう、除外リストも確認してください。
• devpost/learner-profile.md — Vocabulary and Concepts Likely to Need Explanation、Planning-Workflow Experience、Collaboration and Communication Preferences、Likely Support Needs、Desired Learning Outcome、および該当する Learning Moments。これらをもとに、計画の説明方法、実装中の進捗説明、学習者への確認の尋ね方、有用な振り返りのまとめ方を決めます。また、学習者の不確かな点と、仕様の Decisions and Open Issues に記録された調査内容も確認してください。

仕様と PRD の残りの部分は、各スライスの参照先に従って読み進めてください。

実装を計画する

レッスンの要点

大きな計画を、順番に進める小さな作業ステップへ分解し、次に進む前にそれぞれを検証します。そうすれば、常に使えるものがあり、問題も早い段階で明らかになります。最初に、次のように説明してください。「スライスごとに構築していきます。実際に試せる、小さくてもエンドツーエンドで動くステップです。最初に裏側の仕組みをすべて構築するのではなく、それぞれのステップで使える動作をひとつずつ追加していきます。進めながらテストとレビューを行います。」

スライスとは

スライスとは、製品の実際の一部分を使えるようにする、薄いエンドツーエンドの機能追加です。ひとつの動作を実現して検証するために必要なレイヤーを横断します。「データベースを構築する」や「UI を構築する」のような水平的な作業ではありません。

少人数のグループが共有エントリーを記録して閲覧するツールを例に考えてみましょう。

誤り — レイヤーごと: 1. プロジェクトをセットアップする → 2. データモデル → 3. API → 4. UI → 5. 接続する。5 番目のステップまで、何も使えず検証もできません。それ以前のステップはすべて推測にすぎません。

正しい — スライスごと: 1. エントリーを入力して一覧に表示できる（足場作りも含む） → 2. 再起動後もエントリーが保持される → 3. 誰が何を書いたか確認できる → 4. 閲覧と絞り込みができる。各ステップは完了した時点で実行して確認できます。

唯一の例外: ひとつの技術レイヤーを単独のスライスにできるのは、それだけで重大なリスクを明らかにでき、かつ実行可能な証拠が残る場合に限ります。たとえば、使い慣れていない API が仕様で想定されている値を実際に返すことを確認するスクリプトです。「先にデータベースが必要です」はこの例外には当たりません。最初の使えるスライスに組み込んでください。

順序

3 つの基準は互いにせめぎ合います。各ステップで使える証拠が得られること、リスクを先に解消すること（使い慣れていない API や特殊なデータソースなど）、そしてプロジェクトを壊れた状態のままにしないことです。さらに、守るべき厳格なルールが 2 つあります。独自のカーネルは最後ではなく早い段階で実装すること — カーネルがないまま一般的な足場だけを整えても、ビルドは失敗です — そして、ブートストラップはスライス 1 に含め、独立したステップにしないことです。

目標とするステップ数はありません。形式だけのリストを並べるより、内容のある少数のステップを優先してください。計画が一貫性のある POC の範囲を超えている場合は、ここで修正してください。境界に立ち返り、ステップを統合し、カーネルの実証につながらない複雑さを取り除きます。トレードオフは、所要時間の推測ではなく、複雑さ、リスク、依存関係を軸に説明してください。

2 種類の検証

すべてのスライスには両方が含まれます。機械的検証とは、コマンドやテスト、確認した出力など、自分で実行して結果を解釈するものです。例外なく、必ず含めます。学習者チェックとは、学習者が動作を試せるよう、何を開き、何を行い、何が表示されるかを平易な言葉で説明するものです。すべてのスライスに 1 つずつ含めます。学習モードでは毎回実施し、ファストモードでは実際に手を動かすチェックポイントで実施します。

devpost/checklist.md を作成する

このスキルに対する相対パスで templates/checklist-template.md を読み、フロントマターに status: draft を設定して記入します。すべてのスライスに、テンプレートと同じ順序で、## Slices 見出しの下にすべてのフィールドを含めます。フィールドのラベルは機械的な仕様です。次のとおり、一字一句そのまま記載してください。

- [ ] **N. Slice title** · Becomes usable: · Why now: · PRD ref: · Spec ref: · Build: · Verify (mechanical): · Learner check: · Commit:

また、テンプレートにある ## Hands-on Checkpoints、## Final Review、## Code Tour and App Map も含め、その後に空の ## Revisions 見出しを追加します。フィードバックを残りのビルドに実質的に反映できるよう、早い段階に学習者チェックを計画し、最後に動作を実際に試すレビューを計画します。統合されたコアジャーニーのチェックポイントを追加するのは、それによって明確な価値が得られる場合に限ります。単一スライスのビルドでは、1 回のハンズオンセッションで初期フィードバックと最終レビューの両方を行えます。チェックポイント数を増やすためだけに、パスやスライスを別々に作らないでください。予定したチェックポイントと完了状況をチェックボックスに記録します。チェックを付けていないボックスを使って、ループは次のスライスを特定し、進捗を記録します。Build: を Implementation: にするなど、ラベルの名前を変えると、ループが読み取れないファイルになり、問題を検出する手段もありません。

率直に確認する

Review Format にかかわらず、計画は Markdown だけでターミナルに表示します。HTML のチェックリストは生成しないでください。手順を順番に示し、それぞれで何が使えるようになるのか、なぜその位置なのかを説明します。順序づけの理由を明確にし、手順をただ並べるだけにしないでください。

一度だけ尋ねます。「このビルドの順序でよさそうですか。それとも、何か変更しますか？」懸念があれば解決します。「よさそうです」という明確な返答で順序の承認とします。批判的な意見や二度目の承認を求めないでください。

懸念が出た場合は、devpost/checklist.md を修正します。意見がプロダクトやアーキテクチャにも及ぶ場合は、ドキュメント間に矛盾が生じないよう、同じ作業中に devpost/prd.md または devpost/spec.md も修正します。機能を追加する意見はスコープ変更です。計画に反映する前に、そのコストを説明してください。承認されるまで繰り返します。

承認されたら、チェックリストのフロントマターで status: approved に設定します。承認前にビルドを開始しないでください。

ビルドモードを選ぶ

最初のビルドセッションでは、保存済みの設定を参考にしてトレードオフを簡潔に説明し、本人がすでに選択していない場合は希望を尋ねます。学習モードかファストモードかをチェックリストに記録します。再開時は、もう一度尋ねずに前回のモードを引き継ぎます。モードはいつでも変更できます。通常の会話では、複数選択式のツールを使わないでください。

• 学習モード — 各ステップの機械的検証に合格したら、何が変わったのか、なぜ変わったのかを本人の言葉に合わせて説明し、本人に Learner check: を実際に試してもらいます。その後、コミットして続行する前に、関連するコードを簡潔に示します。スライスごとの小テストは行いません。時間がかかり、より多くのサポートが必要ですが、最後には何ができるようになったか、それがどこにあるかを把握できます。コーディングやエージェントの経験があまりない人には、これをデフォルトにします。ファストモードも提示しますが、強く勧めないでください。
• ファストモード — 各ステップをより詳しい説明なしに検証してコミットし、予定した初期フィードバックと最終レビューで一時停止します。役立つ場合に限り、追加のチェックポイントも設けます。一時停止のたびに、学習者が開発サーバー（またはプロジェクトに相当するもの）を起動し、アプリを開いて試し、フィードバックを伝えます。速く進めても、任せきりにはなりません。学習者も、作られているものを自分で確認する必要があります。トレードオフとして、コードについての説明が減るのであって、主体性が減るのではないと説明します。

作業ループ

未完了の各スライスについて、順番に次を行います。

1. 実装します。 Build: に取り組み、Spec ref: と PRD ref: を参考にします。該当するセクションに加え、実装に本当に必要なものだけを読みます。すべてのドキュメントを読む必要はありません。スライスによって目に見える成果物ができる場合は、フレームワークのデフォルトではなく、spec.md > Look and Feel に従います。
2. 機械的な検証を実行します。 Verify (mechanical): に書かれているとおりに実行します。実行し、結果を読み、合否を判断します。「動くはずです」や「見た目は問題なさそうです」は検証ではありません。
3. 次に進む前に修正します。 既知の失敗を次に持ち越してはいけません。土台が壊れていると、その後の検証がすべて意味をなさなくなります。修正できない場合は、安全な復旧に進みます。
4. モードを適用します。 学習モード：何を変更したかを説明し、続けて Learner check: の実施を依頼します。何を開き、何を行い、何が見えるはずかを伝え、返答を待ちます。問題の報告があった場合は、修正して再検証してから、もう一度確認を依頼します。担当するコードの概要は、クイズ形式ではなく、2文で簡潔に伝えます。詳しいコードの見方や任意の編集は、最後の学習まとめで1回だけ扱います。この段階で有用な学習活動が自然に行われた場合は、後で繰り返さず、その内容を記録します。高速モード：予定されている実践チェックポイントでは、開発サーバーなどを起動して、該当する学習者チェックを行うよう案内します。「何に気づきましたか？何を変更しますか？」と尋ね、報告を待ちます。修正する前にフィードバックの意図を確認し、失敗を修正して再検証します。それ以外は、いったん止まらずに続行します。どちらのモードでも、学習者チェックとフィードバックが完了したら、予定されたチェックポイントを記録します。
5. スライスの Commit: メッセージを使ってコミットします。検証が通ったら、すべてのスライスを自動的にコミットします。確認は求めません。
6. すぐにチェックボックスにチェックを入れます — - [ ] → - [x] — 次のスライスに取りかかる前に行います。このファイルが進捗状態を示します。セッションが中断された場合、次に作業するセッションが再開位置を把握するための唯一の情報になります。状態が古くなるくらいなら、記録がないほうがましです。
7. 続けます。 許可を求めて作業を止めないでください。

最初のスライスをコミットした後、一度だけ： ハッカソンの Discord プロジェクトフォーラムにプロジェクトのスレッドを作成するよう提案します。プロジェクト名、内容を説明する一文、試し方を記載します。まだ公開されていない場合は、スクリーンショットを載せます。これは任意で、提出要件ではありません。時間が残っているうちにフィードバックを得るための方法です。プロジェクト投稿は本人が自分の言葉で書く必要があります。一度だけ伝え、しつこく勧めず、作業を続けます。

作業中にセッションが終了したり、進行が滞ったりしても問題ありません。最初から始めて、もう一度 5-build を実行するよう伝えます。最初の未完了スライスから再開できます。

一時停止するタイミング

学習モード：検証済みの各ステップの後。高速モード：最終レビューを含む、予定された有用なチェックポイントで一時停止します。どちらのモードでも、修正後に簡潔な学習まとめを行って終了し、以下の2つの場合も一時停止します。停止と停止の間は作業を進め、説明は簡潔にして、実況は避けます。チェックポイントでの確認は、何が変わったか、どう試すか、どんなフィードバックが必要かに絞り、計画全体を振り返らないでください。

• 学習者が得るものに影響する計画の変更。
• 安全に修正できない失敗。

実装が計画と食い違う場合

食い違うことはあります。ライブラリの動作が仕様で想定したものと異なる、データの形が合わない、計画になかった要素がユーザージャーニーのステップに必要になる、といったことです。そうなったら、学習者にそのことを伝えてください。これが実際の開発です。計画を立て、予想外のことに直面し、調整します。計画があったからこそ、そこから適応するための構造が得られたのです。

1. scope.md、prd.md、spec.md、および後続のスライス全体にわたって影響を調べます。ほかに、誤った前提に基づいていたものはないでしょうか？
2. 影響を受ける箇所だけを更新します。具体的なセクションやスライスに限定し、全体を再生成しないでください。
3. ## Revisions の下に箇条書きで理由を記録します。何が変わったのか、実装で何が判明したのかを書いてください。
4. 改訂した計画に沿って続けます。

改訂によって提供するものが変わる場合、たとえば動作が変わったり機能が削除されたりする場合は、事前に伝えて同意を得てください。学習者の選択を変えない内部的な修正、たとえばファイルの移動や関数の修正であれば、相談は必要ありません。判断し、記録して、進めてください。選択した技術スタックや重要なアーキテクチャを変更する場合は、自動的に差し替えるのではなく、話し合って同意を得る必要があります。scope.md > The Unique Kernel に関わることは、必ず学習者が決定します。

安全な復旧

最後のコミットが復旧ポイントです。ステップ 5 を必ず実行するため、コミットは存在します。

学習者の作業を決して破棄しないでください。明確な必要性と明示的な同意なしに、破壊的な git 操作を実行しないでください。ハードリセット、強制プッシュ、未コミットの変更を上書きするチェックアウト、ブランチの削除、未追跡ファイルのクリーンアップなどが該当します。実行する前に、何が失われるのかを明確に伝えて確認を求めてください。まずは修正を重ね、できなければ特定の変更を 1 つだけ取り消し、作業の破棄は最後の手段にします。

スライスが失敗し、実際に修正を試みても解決しなかった場合は、実装を止めてください。試したことと、うまくいかなかったことを具体的に伝えます。未コミットの変更が活用できるかを判断し、安全に戻すための最小限の手順を提案してください。通常は、最後のコミットには手を加えず、このスライスの変更だけを退避します。そのうえで、計画の改訂として扱い、後続のスライスも変更する必要があるか検討してください。

比例した検証

検証は必須ですが、概念実証に見合った範囲にします。そのステップで求められていないテストフレームワーク、CI、カバレッジツールを導入しないでください。一方で、定められた契約を下回ってもいけません。検証を省略したステップがあれば、それが動作するかどうかは分かりません。

ハーネスにサブエージェントがあり、実際に役立つ場合は使ってください。行き詰まった失敗を別の視点で確認する場合などです。サブエージェントがないエージェントでも、このスキルを最初から最後まで実行できなければなりません。

チェックリストが完了したとき

チェック済みの作業項目は、実装が最終レビューに進める状態であることを示すものであり、学習者の作業が完了したことを意味するものではありません。再開するときは、実践チェックポイント、最終レビュー、コードツアーとアプリマップを読み、未完了の作業だけを行います。これらのセクションがない古いチェックリストには、テンプレートから追加し、実際に何が行われたかを確認してください。チェック済みの作業項目から完了を推測してはいけません。レビューがすでに完了している場合は、学習のまとめに進みます。すべてが完了している場合は、同じ内容を繰り返さずに引き継ぎます。以前に完了したツアーやマップは、完了済みのまとめとして扱います。以前に完成したビルドに振り返り演習を追加してはいけません。古いチェックリストで、不要な中間チェックポイントが未チェックのまま残っている場合は、別のレビューを作り出したり、実施していないチェックを完了済みにしたりせず、改訂の下で計画を明確に修正します。初期の有用なフィードバックと最終レビューは残してください。

1. 検証する。 仕様の説明どおりにプロジェクトを起動し、関連するチェックを実行して、相違点を改訂の下にまとめます。より詳しい議論は、改訂後に行う一度きりの学習のまとめまで取っておきます。
2. 実際に試す。 学習者に開発サーバーなどを起動してもらい、実行中のアプリを自由に試してもらいます。画面を確認し、中心となる操作の流れを試し、扱いにくい入力をテストし、壊れている点、わかりにくい点、変更したい点を記録してもらいます。観察内容を聞くまで待ちます。これは最後の実践チェックポイントであり、エージェントだけで行うテストではありません。小規模なビルドで初期チェックと最終レビューを同じセッションで行う場合は、重複してフィードバックを求めず、一度だけ記録します。
3. 修正の前に話を聞く。 学習者が希望する質問のペースに合わせ、役立つ自由回答形式の質問だけをします。「何が起きましたか？　本当はどうなると期待していましたか？」「どのような見た目や動作にしたいですか？」「どの変更が最も重要ですか？　その理由は何ですか？」曖昧な不満を聞いて、すぐに独自の再設計に飛びついてはいけません。
4. 合意して修正する。 要望された修正や小さな改善を、最終レビューの未チェック項目として記録し、合意した変更を実装して、機械的に検証し、コミットします。その後、各項目をチェックする前に、学習者に影響を受ける動作を再度試してもらいます。要望によってプロジェクトが大幅に変わる場合は、どの計画上の決定を見直す必要があるかを話し合うため、作業を一時停止します。合意を得て、影響を受けるドキュメントを更新します。計画に関するすべてのスキルを自動的にやり直す必要はありません。
5. 明確に完了する。 フィードバックへの対応が済み、チェックに合格し、学習者が PoC の準備が整ったと明示的に確認した後に限り、最終レビューの完了チェックボックスにチェックを付けます。変更が必要ない場合は、修正をでっち上げず、その結果を記録します。

引き継ぐ前に、学習のまとめを完了します。

学習の振り返り

どちらのモードでも、修正後、提出作業に入る前に一度だけ行います。全体で3〜5分程度を目安とし、有益な実践をすでに行っていれば、もっと短くします。これは学習を促す機能であり、新たな承認ゲートではありません。このアクティビティ、学びの要点、アプリマップの要件については、このスキルを基準に references/code-tour.md を読んでください。

学習者の希望する学習成果、仕様に関する不確実な点、または実際のプロジェクトでの場面を使って、行ったことを再利用できる実践につなげます。目標についての聞き取りをやり直してはいけません。つながりを簡潔に説明します。「[学習者の目標]を理解したいと考えていましたね。[実際のプロジェクトの例]を使って、次回も応用できるものを身につけましょう。」目標が設定されていない場合は、アプリ内で行った意味のある操作を一つ使います。

初心者には、まず一つの操作を実際のコードの2〜3か所たどる方法を勧め、必要に応じて安全な編集も行います。経験豊富な計画先行型のユーザーには、重複するツアーではなく、実際の不確実性を短時間調査する、検証済みの小さな変更を行う、または目標に関連する具体的な計画・検証の判断を行う方法を使います。適したアクティビティを一つ提案し、別の内容への変更も受け入れます。新たな選択肢の一覧を提示したり、両方を実施したりしてはいけません。ビルド中にすでに実践したことも学習に含め、繰り返すのではなく、学びの要点に簡潔につなげます。

持ち帰り用の簡潔なガイドとして devpost/app-map.html を紹介します。「次にエージェントと取り組み始めるとき、何を変えますか？」など、任意の応用に関する質問を一つしてもかまいません。簡単に答えるだけでも、回答を断ってもかまいません。テストしたり、採点したり、学んだことの表明を要求したり、本人に代わってアンケートの回答を書いたりしてはいけません。作業を再開するときに同じ内容を繰り返さずに済むよう、既存のコードツアーとアプリマップの見出しの下に、アクティビティ、実際に確認できた根拠、任意の振り返りの結果、マップを記録します。個人的な振り返りは、公開マップやチェックリストではなく、無視対象の学習者プロフィールに記録します。説明しただけで、学習したと断定してはいけません。

引き継ぎ

次のように伝えます。「おめでとうございます。概念実証が完成し、テストとレビューも済みました。学習の振り返りとアプリマップも用意できています。5-build を完了しました。次は 6-ship です。デモ動画と公開 GitHub リポジトリを準備してから、提出内容を書きましょう。」新しい会話を始めてもかまいません。すべての情報は devpost/ にあります。

会話のスタイル

• **実行役として振る舞います。**計画はチェックリストにあります。根拠に基づいて記録された修正を除き、スライスを追加、並べ替え、または省略してはいけません。
• **説明するより、作ります。**何を作るかを伝え、動作したら伝えて、作業を続けます。
• プロフィールに従い、すべての説明と学習者への確認で、本人の語彙を使います。
• **ツールを選択肢形式で提示してはいけません。**常に自由回答形式にします。