cs-build-import-codebase

コードベースを CodeSpring にインポートする

実際のリポジトリを、正確な CodeSpring モデルに変換します：コア機能 → サブ機能 → ノート → PRD → タスク。コードと Git を読み取り、書き込み先は CodeSpring のみです。コードベースは変更しません。

共有ナレッジを確認してください：codespring スキルの references/project-state.md（どこからでも開始する方法、5 つの質問）、references/auditing-and-fixing.md（監査 → 判定 → マップ → タスク、マップにターゲットを表示する理由）、references/analyze-codebase.md、references/mindmap-structure.md（正確なノード／エッジのスキーマ）、references/prd-management.md、references/pitfalls.md。続いて、このスキルの references/target-map.md（マップのルール — ノードモデル、修正されたターゲット、規模を小さく保つ方法）を確認してください。

言語や技術スタックに依存しません。 ここまたは参考資料に記載されている具体例はすべて、ラベル付きの説明例であり、対象リポジトリについての前提ではありません。

スクリプトのパスは、このスキルのフォルダーを基準とします。スキルは同じ階層にインストールされるため、../codespring/scripts/… でコアスキルのスクリプトにアクセスできます。最初に絶対パスへ解決してください。作業ディレクトリはユーザーのリポジトリになります。

0. プロジェクトの現在の状態を検出する

手作業で数えるのではなく、状態検出 スクリプトを実行してください（このスキルと同じ階層にインストールされた codespring スキルの scripts/ にあります）。

bash ../codespring/scripts/fetch-project.sh --out /tmp/cs-state   # read-only snapshot; prints the projectId
node ../codespring/scripts/state.mjs       /tmp/cs-state          # summary line + booleans and counts
node ../codespring/scripts/check-map.mjs   /tmp/cs-state          # machine-checkable map faults, before you add to them

書き込みを行う前に、ローカルの .codespring/config.json から projectId を読み取り、表示してください。

現在の状態に応じて分岐してください。何もない状態から始めると決めつけないでください。

• すでにマップがある → インポートではなく更新です。既存のコア機能と ID を表示してから、マップ品質の段階的な確認（以下）を実施してください。タイトルで照合し、再作成はせず、誤った親に属する項目を付け替えます。不足しているもの（ノート → PRD → タスク）だけに進んでください。
• 未リンク → リンクします。チームのワークスペースにプロジェクトを置く必要がある場合は、ユーザーが先に Web アプリでプロジェクトを作成します（プロジェクトの配置や移動を行う CLI の方法はありません — pitfalls.md）。
• タスクがある → 最大番号を記録し、続きの番号から進めます。
• このアプリに対するプロジェクトがすでに 2 つある → 書き込みの前に、どちらが正式なプロジェクトかを確認し、ユーザーに伝えてください。

0a. マップ品質の段階的な確認 — 既存のマップが必ずしも良いマップとは限りません

*「マップがある → そのまま使う」*では不十分です。使いものにならないマップは、そこから作成するすべてのノート、PRD、タスクの品質を損ないます。CLI コマンドとプロジェクトが 2 つある場合の警告を含む完全版は、references/target-map.md を参照してください。

1. マップはありますか？ ない → §2～§4 に従って作成します。
2. マップの品質は十分ですか？ check-map.mjs で項目数、重複タイトル、平坦化されたサブ機能、ノートの欠落を確認します。その他の点はあなたが判断してください。コア機能は 4～8 個にし、それぞれユーザーがサイドバーの項目として認識できるものにします。サブ機能は、出力ドキュメントのセクションやフォーム項目のグループではなく、ユーザーが行うことを表すものにします。カードの説明は 1 文とし、詳細はノートカードに記載します。すべてのチェックに合格しても、理解しにくいマップはあり得ます。
3. 問題がなければ、そのまま使います。 ノートを更新し、タスクを追加します。再作成してはいけません。
4. 修正可能（ほぼ正しいが、少数の項目が誤っている）→ 既存のマップを修正し、変更内容を伝えます： codespring feature update <subId> --parent <coreId>、codespring feature delete <dupId> --yes、codespring feature update <id> --title "..."。
5. 修正不可能（コア機能が大幅に多すぎる、出力ドキュメントのセクションを機能として扱っている、まとまりのある構造がない）→ 修復しようとしてはいけません。 理由を明確に説明し、整理されたマップを備えた新しい CodeSpring プロジェクトを推奨してください。古いプロジェクトは履歴として残ることも伝えます。2 つ目のプロジェクトを作成する前に、必ず明示的な確認を得てください。無断で作成してはいけません。 同じアプリにプロジェクトが 2 つあると、後で混乱するため、意図を説明したうえで選択する必要があります。また、どちらが正式なプロジェクトになったかをユーザーに伝えてください。（実例：コア機能が 13 個あるインポートは使いものにならず、整理された 6 個の機能を備えた 2 つ目のプロジェクトに置き換えられました。両方とも残っており、project delete はありません。）

1. 監査は実施済みですか？

出力を変える入力はこれだけです。

	動作
監査なし	現状にあるもの、つまり現在のアプリを記録します。
監査＋判定	修正後の目標マップを作成します。アプリがどうあるべきかを、専門知識のない人にも分かる中核機能に整理します。

監査がない場合は、インポートする前に5つの質問（project-state.md）をしてください。アプリは必要なことを実行できているか、誤った情報を示したり、検証できない数値を事実として提示したりしていないか、アーキテクチャは必要な処理を実現できるか、スケーラブルに構築できるか、ユーザーが問題なく使えるか、という質問です。1つでも「いいえ」があれば、まず監査を提案してください。「コードを信頼していますか」と尋ねてはいけません。また、「動作する」を5つすべての「はい」として受け入れてはいけません。「コードが実行される」ことと「コードが目的を果たす」ことは同じではありません。

次に、簡易的な健全性チェック（project-state.md）を実施してください。ユーザーは知識だけでは質問2、4、5に答えられないことがよくあるためです。確認する兆候は6つです。テスト／CI がない、承認なしでデプロイされる、ローカルのクローンがリモートより古い、エラーが握りつぶされる、出荷されるソースコードに認証情報が含まれている、ブラウザー内だけに記録がある、または参照データがハードコードされている、です。**2つ以上あれば、作業を止めて監査を提案してください。**率直に伝えます。*「アプリのマッピング前に診断が必要となることが多い6つの兆候のうち、4つが見つかりました。先に cs-build-audit-codebase を実行しますか？」*問題のある状態を黙ってインポートしてはいけません。壊れたアプリのマップは、誰も信頼すべきではないマップです。ユーザーが断った場合は、現状にあるものをインポートし、そのマップは問題点も含めて現時点の動作を記録するものだと伝えてください。

2. コードを分析する

analyze-codebase.md に従ってください。フロントエンドのマップ（ルート、コンポーネント、ユーザーに表示される内容、ナビゲーション）とバックエンドのマップ（API ルートと、それらを共有する機能、データモデル、セキュリティ、共有システム — 決済／クレジット、ジョブ／cron、ストレージ、認証、環境変数 — およびインフラ）を作成します。実際の技術スタックを特定してください。推測せず、ファイルを読んでください。監査の手順では、必要な情報の大半がすでに得られています。再度分析するのではなく、その調査結果を活用してください。

3. 機能を決める — 認識可能な最小セット

ルールと実際に起きた失敗については、references/target-map.md を参照してください。要点は次のとおりです。

• コア機能＝ユーザーが指し示すような、サイドバー／ナビゲーションのレベルの項目です。4～8個を目指してください。最初の実行では、分かりにくいコア機能が13個できましたが、方向を修正した後は、明確なものが6個になりました。可能な限り、最小のセットを目指してください。
• サブ機能＝ユーザーが行うことです。動詞で表現します。顧客を保存する。2つの物件を比較する。PDFをエクスポートする。
• **繰り返してはいけない間違い：レポート／ページのセクションやフォームのフィールドグループをサブ機能にしないでください。**レポートのセクションは1つの機能の出力の一部であり、フォームのフィールドグループは1つの機能の入力の一部です。レポートにセクションが12個あるなら、機能は1つで、適切な注記を付けます。機能を12個に分けるのではありません。
• **カードの説明は短い1文にとどめてください。詳細情報はすべて、ブリッジを介してその機能に紐づくノートカードに記載し、カードの説明には決して記載しないでください。**ノードモデル（機能ノード → カード → ブリッジ → ノートカード、およびブリッジ → PRDブリッジ → PRD）についてはreferences/target-map.md、正確なスキーマについてはmindmap-structure.mdを参照してください。最初の実行でまさにこの問題が起きました。カードに長い説明を記載したうえ、出力セクションをサブ機能に格上げしたため、使いものにならないコア機能が13個できてしまいました。
• CLIではノートを作成できるのはルート機能だけです。そのため、サブ機能の詳細は親となるコア機能のノートに記載します（pitfalls.md §5）。

監査の手順では、現在のアプリにない機能を追加するのは、バケット1の修正を置く場所がほかにない場合に限ります（ブラウザー内にしか存在しないレコードの永続ストレージ、サインイン機能がない場合のサインインなど）。バケット2の「後から追加できる」アイデアが機能になることはありません（auditing-and-fixing.md §4a）。

**アプリの機能が完成しているのか、まだ開発中なのかを確認してください。**まだ開発中なら、リストを確定する前に、これから実装する予定で、まだ実装されていないものを尋ねてください。コードがないからといって、機能がないとは限りません。また、リンクがまったくないページは、行き止まりや別製品ではなく、未完成のモジュールかもしれません。

何かを書く前に、リストをユーザーに読み上げ、削る項目を尋ねてください。

4. マップを作成する（CLI）

codespring mindmap set-info --title "..." --description "..." --github "<repo url>"
codespring mindmap tech-stack --replace --add '[{"id":"tech-...","title":"...","description":"Frontend"}, ...]'
codespring mindmap features --add '[{"title":"Dashboard","description":"..."}, ...]'   # CORE features; keep the returned ids
codespring feature create --parent <coreId> --title "..." --description "..."           # sub-features
codespring mindmap note <coreId> --title "How it works — X" --text "$(cat note.txt)"    # one per core feature; redirect output to /dev/null

**冪等性（auditing-and-fixing.md §8）：まずタイトルで差分を確認し、不足しているものだけを追加してください。codespring mindmap features --replace は置き換えを行いません。追加するため、重複が作成されます。**重複が発生した場合は、正常に動作し、関連項目も連鎖的に削除するcodespring feature delete <id> --yesで復旧してください。

各コア機能のノートには、analyze-codebase.md §8–9で説明している詳細と、監査の手順では次の3点を記載します。機能が本来どう動作すべきか、現在どのように動作しているか、現在の問題点（深刻度とファイルの参照先。再構築の場合は、「再発させてはならない」制約も含む）。PRDジェネレーターはこのノートをコンテキストとして読み取るため、ノートが簡素だとPRDも簡素になります。既存のノートを更新する際は、まずその内容を読み、今も正しい情報は残してください。

5. マップについて説明する

誤解を防ぐため、ユーザーには1文で伝えてください。**マップが示すのは修正後の目標であり、現在の構成ではありません。そのため、タスクが完了するまではリポジトリの構成と一致せず、カンバンはその2つの間のギャップを示します。**理由はreferences/target-map.mdに記載されています。これは意図的なもので、どちらの判定結果にも当てはまります。

6. PRD — cs-build-create-prdを使用する

PRDの仕組みを再実装しないでください。各コア機能には**cs-build-create-prd**（フロントエンドとバックエンドの両方）を使用してください。これにより、共有バックエンドの契約が取り込まれ、PRDブリッジノードが正しく紐づけられます。タイムアウトが120秒以上であることと、重複排除のルールに注意してください。すでに存在するPRDは、依頼されない限り絶対に再生成しないでください。まず既存のPRDを読み、存在することを伝え、更新を提案してください。また、ノートがない機能のPRDは生成しないでください。

7. タスク — 2つの進め方は異なります。ここが重要です

タスクになるのは**バケット1（実際の問題）**だけです。各タスクは、1つのコア機能だけに紐づけ、重要度（Critical → urgent、High → high、Medium → medium、Low → low）を設定し、タイトルは1文で、詳細は説明に記載し、既存の番号を引き継ぎます。

将来のアイデアを CodeSpring に置く場所はなく、タスクにしてはいけません — タスクリストは、作業が確定したことを意味します。バケット2と3は、リポジトリ内の FINDINGS.md に、明示的なタイトルとそれぞれ1行の理由を添えた2つのセクションとして記載します。「後で追加できる — 今は意図的に追加しない」 と 「追加する価値がない」 です。マップには載せず、カンバンにも載せず、PRDにもしてはいけません（auditing-and-fixing.md §4a — FERB における既知のプロダクト上のギャップです）。

判定 = REBUILD → 明確に分けた2種類のタスク。

1. 仕様に基づく構築タスク — 機能／サブ機能ごとに1つずつ、基盤から着手します。
2. 「避けるべき間違い」タスク — 元の実装で見つかった重大な欠陥ごとに1つずつ作成し、具体例を添えた明示的な再発禁止の制約として引き継ぎます。2つ目のタスク群こそ、インポート前に監査を行う理由そのものです — これがなければ、新しい計画には再発を防ぐ指示がないため、再構築で同じ見過ごされる失敗、同じハードコードされたテーブル、同じ重複ロジックが再現されます。検証可能な制約として記述します。
   • 「参照データは、コードに値を直接入力するのではなく、日付付きのレコードに保存します。アプリを編集してレートを変更することはできないようにします。」
   • 「検索結果がない場合は、その旨を表示します。エラーが発生した箇所にゼロや空欄を入れるコードパスがあってはなりません。」
   • 「計算ロジックは1か所だけに存在し、すべての処理がそのロジックをインポートします。」
   • 「レポートを公開するときは、入力値、結果、適用した年のレートを保存します。後でレートを修正しても、すでにクライアントに提示した内容は変わりません。」
   • 「リクエスト本文からユーザーの身元を判断してはなりません。リクエスト内の識別子は対象を示すものであり、使用前に所有権を確認します。」

判定 = FIX IN PLACE → タスク群は1つ。 欠陥ごとに、その欠陥が存在する場所でタスクを1つ作成し、説明にファイル参照を記載します（ユーザー向けの指摘にはパスがありませんが、エージェントが作業するにはタスクにパスが必要です）。順序は、見過ごされる失敗、誤った出力、構造的な作業、仕上げの順です。監査で修正順序が提案されている場合は、その順序に従います。

監査なし → タスクは指摘事項ではなくPRDから作成します。その場合は cs-build-create-tasks に引き継いでください。PRD由来のタスクリストはこのスキルの担当です。このスキルが作成するのは指摘事項由来のタスクだけです。指摘事項が存在するのはここだけだからです。

UNVERIFIED の指摘事項は、そのラベルを維持した調査タスクにします。確定的な修正タスクにしてはいけません。

8. 検証（pitfalls.md、auditing-and-fixing.md §9）

目視で済ませず、チェックを実行してください。

bash ../codespring/scripts/fetch-project.sh --out /tmp/cs-verify
node ../codespring/scripts/check-map.mjs   /tmp/cs-verify --expect-core <the count you intended>

• node-features.items.length が想定するコア機能数と一致し、サブ機能がトップレベルに平坦化されていないことを確認します。誤った親に紐づいた項目は codespring feature update <subId> --parent <coreId> で親を付け直します。サブ機能からコア機能への対応表を保持し、再実行を1コマンドで済ませられるようにします。
• 機能の重複（タイトルで判定）とPRDの重複（機能＋種類で判定）がないことを確認します。
• コア機能ごとにノートが1つあることを確認します。すべてのタスクが機能と重要度に紐づいていることを確認します。
• ゼロ以外の終了コードは実際の失敗です。報告する前に修正します。その後、差分を報告します。作成 N 件、更新 N 件、スキップ N 件。プロジェクトリンク https://v2.codespring.app/project/<projectId> を提示します。

9. マップの任意の独立監査（監査なしの経路のみ）

監査を行う経路では、すでに監査済みなので、この手順はスキップします。それ以外の場合は、インポート作業のコンテキストを一切与えず、完全に自己完結した指示を添えてバックグラウンドのサブエージェントを起動し、比較に偏りが生じないようにします。

あなたは独立した監査担当者です。読み取り専用です。コードベースやCodeSpringのマップを変更しないでください。

1. コードベース全体を棚卸しします — すべてのルート、ページ、テーブルと列挙型、外部プロバイダー、Webhook、cron／ジョブ、共有バックエンドの契約（決済／クレジット／返金、ジョブパイプライン、ストレージ規約、認証、環境変数）。
2. CodeSpringに記載されているすべての内容を読みます — 各機能のメモとPRD（codespring CLIを使用）。
3. 批判的に比較して報告します。優先するのは、共有バックエンドの不足や競合リスク（新機能追加において最もリスクの高い部分）です。コードにあるのに文書化されていないもの、共有システムを破損させたり重複させたりする可能性があるもの、文書化されているものの重要なバックエンドの詳細が欠けているものをすべて指摘してください。それぞれに重大度を付け、正確なファイル／ルート／テーブルの参照を示してください。さらに、CodeSpringに追加する内容の候補を絞って提示してください。

完了したら報告し、候補をメモ／PRDに反映するか、cs-build-resync-codebaseに引き継ぐかを提案してください。

適切な状態

• マップには、専門家でない人にも認識できる、核となる機能の最小限のセットを記載します。報告セクションやフォームのフィールドグループは含めません。
• 監査を行った場合、マップは修正済みの目標状態となっており、その旨をユーザーに一文で伝えています。監査を行わない場合は、現状を正直に記録しています。
• 重複はありません。既存のマップを基準に照らして評価し、そのまま維持するか、該当箇所で修正しています。機能はタイトルで照合し、行き場のない項目は親項目に付け替え、既存のPRDには手を加えていません。
• 2つ目のCodeSpringプロジェクトを作成したのは、明示的な確認を得た場合に限られ、その理由を説明し、正式なプロジェクトを明示しています。
• 将来のアイデアは、指定された2つのFINDINGS.mdセクションに記載し、マップにもKanbanにも載せていません。
• すべての核となる機能に実際の「仕組み」のメモがあり、すべてのPRDはそのメモをもとに生成されています。
• 再構築する場合、元の不具合が再発しないよう、「避けるべき間違い」をまとめた別個のタスク群があります。既存の箇所を修正する場合は、それぞれの不具合が実際に存在する場所にタスクがあります。