AIで開発・運用を進めるための土台地図

0. まず前提: 限界ではなく「地図なしで進んでいる」状態

非エンジニアがAIで開発を進めると、見た目の成果がすぐ出ます。HTMLができる、アプリが動く、画像や動画も作れる。問題は、成果物の裏側にある「どこを触ると危ないか」「何が再生成できるか」「本番に影響するか」という地図を持たないまま速度だけが出ることです。

大事な考え方: AIを賢くするより、AIが迷わない構造にする。AIに任せる範囲を狭く、明確に、戻せる形にする。

エンジニア経験者は、コードを書く力だけでなく「作業範囲を切る」「消してよいものを見分ける」「本番事故を避ける」ための感覚を持っています。ここを後から学べば、非エンジニアでもAIをかなり実務的に使えます。

目指す地点: すぐにフルスタックエンジニアになる必要はありません。まずは、AIの提案に対して「どこが危ないか」「何を確認すれば十分と言えるか」を判断できる状態を目指します。

1. AI活用のために学ぶべき範囲

挙げてくれた8分野は、方向性としてかなり良いです。ただし、非エンジニアがAIを使いこなす目的なら、全部を均等に勉強するのはベストではありません。重要なのは「コードを全部自分で書ける」ことではなく、「AIに正しく依頼し、結果の危険度を判断できる」ことです。

結論: 8分野を浅く7割理解する方針は有効。ただし優先順位は、コンピュータ基礎より先に「Web/API、DB、Git、テスト、セキュリティ、開発フロー」を厚めにします。

分野	優先度	目標理解	あなたの用途で重要な理由
① コンピュータ基礎	中	30〜50%	ターミナル、ファイル、環境変数、プロセスが分かれば十分。CPUやスレッドは浅くてよい。
② プログラミング基礎	中	50〜60%	自分で全部書くより、AIのコードを読んで「条件分岐」「エラー処理」「非同期」が危なそうか見るため。
③ Webの仕組み	高	70%	LINE CRM、管理画面、API、ログイン、WebhookはほぼWebの話。ここは厚めに必要。
④ データベース	高	70%	顧客、タグ、配信履歴、クーポン、来店記録を扱うため。間違えるとデータ破壊や誤配信につながる。
⑤ Git	高	70%	AIの変更を戻せるようにするため。`status`, `diff`, `commit`, `push` は必須。
⑥ テスト・品質	最重要	70〜80%	「これで十分か」を判断するため。非エンジニアがAI開発するなら最も差が出る。
⑦ セキュリティ	最重要	70%	LINE、顧客情報、APIキー、管理画面に関わるため。細かい攻撃手法より「危ない形」を見抜く。
⑧ 開発フロー	最重要	80%	AIを使うほど、要件、設計、実装、テスト、デプロイを分ける力が重要になる。

追いつける領域か

「プロのエンジニアと同じ深さで全部理解する」という意味では短期では難しいです。ただし、AIを使って自分の事業の開発を進める責任者として、リスクを判断し、AIに必要な確認を要求し、外部のエンジニアに正しく相談できるレベルには十分追いつけます。

目標設定: コードを一人で全部書ける人ではなく、「AIが作ったものを事業責任者として安全に採用できる人」を目指す。

理解度7割の定義

理解レベル	できること
3割	用語を聞いたことがあり、ざっくり意味を説明できる。
5割	AIの説明を読んで、どの部分の話か分かる。
7割	何が壊れそうか、どんな確認やテストが必要かをAIに要求できる。
9割	自分で実装方針を設計し、細かいコードの妥当性までレビューできる。

2. 最初に理解すべき8つの概念

1. プロジェクトルート

作業の起点になるフォルダ。AIに「ここを見て」と言うときの範囲です。

/Users/hatano/Desktop/spa/spaweb と /Users/hatano/Desktop/spa では、AIが見る世界がまったく違います。

2. ソース

人間が編集する本体。アプリやスクリプトの原稿です。

例: src/, app/, scripts/, *.py, *.ts

3. 生成物

ビルドや実行で自動作成されるもの。消しても再生成できることが多いです。

例: .next, out, dist, .open-next

4. 依存関係

アプリを動かすために外部から入れるライブラリ群。

例: node_modules, .venv。基本は再インストール可能ですが、消す前に確認します。

5. 素材

画像・動画・音声・元データ。消すと戻らないことが多いです。

生成物と違い、まずアーカイブ候補として扱います。

6. シークレット

漏れると事故になる情報。AIにも値を読ませないのが基本です。

例: .env, token.json, *.key, APIキー, パスワード

7. Git

変更履歴を残す仕組み。ファイル名に v2 や final を増やす代わりに使います。

8. 本番影響

ファイル変更が実際の顧客・スタッフ・外部サービスに影響するか。

LINE、Cloudflare、GitHub Actions、D1、Firebase、スマレジなどは特に注意。

3. プロジェクトルートは覚えなくてよい

毎回 /Users/hatano/Desktop/spa/ledian-staff のような深いパスを覚える必要はありません。非エンジニアがAIを実務で使うなら、パスを暗記する運用ではなく、「事業名や目的を伝えて、AIに候補を出させる」運用のほうが安全です。

基本方針: ユーザーは spa や cherimi くらいまで指定できれば十分。その先はCodexに探索させ、候補を見て選ぶ。

Codexに探させる時の見るべき目印

目印	意味
`.git`	Gitで管理されているプロジェクトの可能性が高い
`package.json`	Node/Next.js系アプリの可能性が高い
`requirements.txt`	Python系プロジェクトの可能性が高い
`wrangler.toml`, `wrangler.jsonc`	Cloudflare Worker / Pagesに関係する可能性が高い
`README.md`	プロジェクト説明がある可能性が高い
`CLAUDE.md`, `AGENTS.md`	AI向けの作業ルールがある可能性が高い

プロジェクト地図を作る

毎回探す手間を減らすには、事業ごとに「プロジェクト地図」を作ります。これは深いパスを覚えるためではなく、AIに「この名前ならこのフォルダ」と分からせるための索引です。

Desktop/spa 配下の主要プロジェクト地図を作って。プロジェクト名、パス、用途、本番/開発/実験、触る前の注意点を表にして。削除・移動・修正はしないで。

4. フォルダを見るときの分類

分類	意味	AIへの指示
本番稼働中	実際に顧客・スタッフ・外部通知に影響する	「変更前に必ず本番影響を確認して」
開発中	これから触る。未コミット変更がある	「まずgit statusと差分を分類して」
実験	試したもの。今使っているか不明	「休眠候補として棚卸しして。削除はしないで」
素材	画像、動画、音声、元データ	「削除ではなくアーカイブ候補にして」
生成物	ビルドや出力でできたもの	「再生成可能か確認してから整理候補にして」
秘密情報	APIキー、token、password、認証ファイル	「値は読まず、場所と種類だけ報告して」

5. AIに渡すべき情報、渡してはいけない情報

渡すべき情報

事業の概要
このフォルダの役割
本番か実験か
触ってよい場所
触る前に確認する場所
ユーザーや顧客に影響する条件
実行してよいテストや確認コマンド

渡してはいけない情報

APIキーの値
パスワード
アクセストークン
秘密鍵
cookie
顧客データの中身
外部Webhook URLの値

Codex向け: AGENTS.md には「秘密情報の場所」は書いてよいですが、「値」は書きません。例: .env.local にFirebase設定あり。値は表示しない。

6. Gitの最低限

Gitは「やり直せるようにする仕組み」です。非エンジニアがAIを使うなら、全部を覚える必要はありません。まずはこの4つだけで十分です。

言葉	意味	感覚
`status`	今、何が変わっているか見る	作業前後の健康診断
`diff`	どこがどう変わったか見る	変更内容の明細
`commit`	ローカルに変更を記録する	セーブポイント
`push`	GitHubへ送る	外に出す。Actionsやdeployが動くことがある

重要: commitはローカル記録、pushは外部送信、deployは本番反映の可能性があります。AIに任せる場合も、この3つを混同しないこと。

7. シークレット管理

シークレットは「便利な設定」ではなく、鍵です。漏れると外部サービスを勝手に使われたり、顧客情報にアクセスされたり、本番を壊されたりします。

よくあるシークレット

.env
.env.local
token.json
credentials.json
*.key, *.pem
API_KEY, CLIENT_SECRET, ACCESS_TOKEN

AIへの安全な依頼

こう頼む:

秘密情報の値は読まず、ファイルパスと変数名だけ一覧にして。

こう頼まない:

.envの中身を見て設定して。

最優先ルール: Gitに入れてはいけない。AIの回答にも出してはいけない。スクショにもなるべく写さない。

8. 環境変数とは何か

環境変数は、アプリやスクリプトに外から渡す設定値です。環境変数そのものが必ず秘密情報という意味ではありません。ただし、APIキー、アクセストークン、パスワードなど、漏れたらまずい値が入ることが多いです。

正確な理解: 環境変数 = 外から渡す設定値。シークレット = その中でも漏れたら危険な値。

公開されてもよいことが多い例

NEXT_PUBLIC_BASE_URL
NEXT_PUBLIC_API_URL
APP_ENV
REGION

ただし、URLでも管理画面や内部APIを指している場合は注意します。

危険扱いする例

API_KEY
ACCESS_TOKEN
CLIENT_SECRET
PASSWORD
DATABASE_URL
PRIVATE_KEY

`.env` ファイルの役割

.env, .env.local, .env.production は、環境変数をまとめて置くファイルです。コード本体には鍵を書かず、コードからは process.env.LINE_CHANNEL_ACCESS_TOKEN のように呼び出します。

重要: .env は基本的にGitに入れません。AIにも値を読ませません。確認するときは「変数名だけ見て」と頼みます。

`NEXT_PUBLIC_` の注意点

Next.jsでは、NEXT_PUBLIC_ が付く環境変数はブラウザ側に見える前提です。つまり、ユーザーの画面に届く可能性があります。

名前	判断	理由
`NEXT_PUBLIC_BASE_URL`	多くの場合OK	公開URLなら秘密ではないため
`NEXT_PUBLIC_API_URL`	要確認	公開APIならOK。管理用APIなら危険
`NEXT_PUBLIC_ADMIN_TOKEN`	危険	PUBLICとTOKENが同居しており、ブラウザに管理用トークンが出る可能性がある

AIへの安全な頼み方

.envの値は表示しないで。変数名だけ一覧化して、公開されてもよいもの・危険なもの・判断保留に分類して。

9. 要件そのものが安全かを見る

不安の正体は、テストだけではありません。そもそも要件や設計が危ない場合、あとからテストを増やしても事故は避けにくいです。特にLINE CRMのように「誰に何を送るか」を扱うものは、実装前に誤送を防ぐための条件を要件に入れる必要があります。

重要: 「この機能を作って」だけでは足りません。「間違った相手に送らないために、どの確認を必須にするか」まで要件です。

危ない要件の例

要件	何が危ないか	安全な要件に直すなら
タグ条件に合う人へ一括送信する	条件ミスで想定外の人に送る	送信前に対象人数、対象条件、サンプルユーザーを必ず表示する
管理画面から本番送信できる	操作ミスで即時送信される	テスト送信、プレビュー、二段階確認、本番送信権限を分ける
Webhookを受けて自動返信する	偽リクエストや重複イベントで誤返信する	署名検証、イベントID重複防止、許可イベント種別の限定を必須にする
配信予約を変更できる	変更履歴がなく、誰が何を変えたか追えない	変更履歴、変更者、変更前後、キャンセル可否を残す
CSVで顧客を取り込む	列ずれ、重複、別店舗データ混入が起きる	取り込み前プレビュー、件数差分、重複チェック、ドライランを必須にする

誤送を防ぐための設計ガード

送信前ガード

対象人数を表示する
対象条件を日本語で表示する
対象ユーザーのサンプルを表示する
除外条件を表示する
テスト送信を先に必須にする

操作ガード

本番送信は二段階確認にする
送信権限を分ける
即時送信ではなく予約にする
キャンセル可能時間を作る
危険操作は確認文を入力させる

データガード

空条件なら送信しない
対象人数が急増したら止める
店舗/ブランドの混在を検知する
重複ユーザーを除外する
送信済みIDを記録する

監査ガード

誰が送信したか残す
いつ送信したか残す
どの条件で送ったか残す
送信結果件数を残す
失敗理由を残す

AIに要件レビューを頼む文面

この要件を、実装前に安全性レビューして。特に誤送、二重送信、対象者違い、QA/本番混同、権限不足、監査ログ不足、キャンセル不能のリスクを見て。危ない要件を安全な要件に書き換えて。

このLINE配信機能について、実装ではなく要件の抜け漏れを見て。送信前にユーザーが確認すべき情報、必須ガード、異常時の停止条件、ログに残すべき項目を出して。

要件が安全と言える最低条件

誰に送るかを送信前に確認できる
何を送るかを送信前に確認できる
何人に送るかを送信前に確認できる
テスト送信と本番送信が分かれている
本番送信には二段階確認がある
空条件や異常な大量対象では止まる
二重送信を防ぐ仕組みがある
誰が何をしたか後から追える
問題発生時に送信停止または取り消しの方針がある

10. 「テストは十分か」を判断する考え方

テストは「エラーリスクをゼロにするもの」ではありません。ゼロにはできません。テストの目的は、重要な失敗パターンを先に見つけること、そして残るリスクを把握したうえで公開判断できる状態にすることです。

重要: 「動いた」は十分なテストではありません。「壊れやすい場所を意図的に確認した」がテストです。

テスト/確認	何を確認するか	非エンジニアの判断ポイント
静的チェック	文法ミス、型の不整合、lintエラー	まず機械的なミスがないか。`npm run lint` や `tsc` など。
単体テスト	関数や小さい処理が正しく動くか	配信対象の絞り込み、署名検証、URL置換など、小さいロジックに向く。
結合テスト	API、DB、外部サービス風の処理をつないで確認	LINE webhook、D1、管理画面APIなどはここが重要。
E2Eテスト	ユーザー操作に近い流れで確認	管理画面で作成→保存→送信予約→確認、のような実利用に近い確認。
ドライラン	本番送信や本番更新をせずに結果だけ見る	「誰に送られる予定か」「何件更新されるか」を実行前に見る。
スモークテスト	公開前に最低限の主要機能が生きているか	ログイン、一覧表示、保存、送信テストなど最重要だけを見る。
ログ確認	エラー時に原因を追えるか	成功/失敗/対象ID/件数が残るか。秘密情報をログに出していないか。
ロールバック確認	問題発生時に戻せるか	前のcommitに戻せるか、DB変更を戻せるか、送信停止できるか。

AIに聞くべき質問

この変更について、テスト済み・未テスト・手動確認が必要な項目を表にして。特に本番事故、データ破壊、誤配信、認証漏れ、二重送信のリスクを見て。

このテストで十分と言えるかレビューして。足りないテストを、重大度順に出して。修正はまだしないで。

十分性の目安

本番に近い変更ほど、単体テストだけでは足りない。
顧客データや配信に関係するなら、ドライランと手動確認が必要。
DB migrationは、適用前後の状態と戻し方を確認する。
Webhookは、正しい署名、間違った署名、重複イベント、空データを確認する。
「正常系」だけでなく、「失敗したときに安全に止まるか」を見る。

11. LINE CRM開発で特に見るべきリスク

LINE CRMは、普通のWebサイトよりリスクが高いです。理由は、顧客情報、メッセージ配信、外部API、Webhook、DB、管理画面がつながっているからです。画面が動くだけでは十分ではありません。

領域	起きる事故	確認すべきこと
認証/権限	管理者以外が操作できる、公開トークンで操作できる	管理APIに認証が必要か。`NEXT_PUBLIC_` に管理トークンがないか。
Webhook	偽のリクエストを受ける、同じイベントを二重処理する	署名検証、重複防止、失敗時の再試行を確認。
配信	誤配信、二重送信、対象者違い	送信前プレビュー、対象件数、ドライラン、テスト送信、本番送信の分離。
セグメント/タグ	意図しない顧客に配信される	条件のAND/OR、除外条件、空条件の扱い、対象件数の表示。
DB migration	既存データが壊れる、戻せない	新規テーブル/カラム、既存データへの影響、rollback方針、バックアップ。
環境分離	QAのつもりで本番LINEに送る	QA/本番のtoken、DB、URL、送信先が明確に分かれているか。
ログ	問題発生時に追えない、逆に秘密情報を出す	配信ID、ユーザーIDの扱い、件数、エラー理由。tokenや秘密情報は出さない。
外部API制限	レート制限、失敗時の途中停止	失敗時の再試行、部分成功、送信済み管理、タイムアウト処理。

LINE CRMで最低限ほしい確認セット

本番とQAの環境変数が分かれている
管理トークンや秘密情報がブラウザ側に出ていない
Webhook署名の正常/異常テストがある
同じイベントを2回受けても二重処理しない
配信対象を送信前に確認できる
テスト送信と本番送信が明確に分かれている
DB migrationの影響範囲が説明されている
失敗時にログから原因を追える
本番反映前に戻し方が分かっている

LINE CRMのこの変更を、本番事故の観点でレビューして。誤配信、二重送信、認証漏れ、DB破壊、QA/本番混同、ログ漏洩を重点的に見て。テスト不足を重大度順に出して。修正はまだしないで。

12. AIに作業させるときの安全な順番

対象フォルダを1つに絞る
git status で作業前の状態を見る
README / CLAUDE.md / AGENTS.md を読む
本番影響、秘密情報、外部連携を確認する
AIに「変更案」だけ出させる
問題なければ小さく変更する
テスト、ビルド、画面確認をする
commit案を作る
pushやdeployは最後に別判断する

そのまま使える依頼文

このフォルダを整理候補としてレビューして。削除・移動・修正はまだしないで。ソース、生成物、依存関係、素材、秘密情報、本番影響に分けて一覧化して。

この変更の本番影響を見て。GitHub Actions、Cloudflare、LINE、DB、env/secrets、外部APIへの影響を優先して確認して。修正やpushはまだしないで。

13. あなたの環境でまず整える順番

Step 1

秘密情報のignore漏れを確認する。

特に token.json, credentials, .env, *.key

Step 2

cherimi と spa の AGENTS.md を作る。

事業概要、触るな、確認必須、秘密情報の扱いを書く。

Step 3

現役・休眠・素材・生成物を分ける。

いきなり削除せず、まず分類表にする。

Step 4

本番系repoの未コミット変更を分類する。

CRM、LINE、Cloudflare、Actionsは特に慎重。

Step 5

キャッシュと生成物だけ整理する。

node_modules, .next, .wrangler など。

Step 6

ファイル名の v2/final/draft を減らす。

履歴はGitへ。最新版ファイル名はシンプルに。

14. 非エンジニア向けの学び方

いきなりプログラミング言語を深く学ぶより、AIに作業させるための「判断の基礎」を先に覚えるほうが効率的です。特にLINE CRMのような本番連携ありの開発では、コード文法よりも「Web/API、DB、テスト、セキュリティ、開発フロー」の理解が効きます。

段階	学ぶこと	できるようになること
Step 1	フォルダ分類、プロジェクトルート、ソース/生成物/素材	AIに安全な作業範囲を渡せる
Step 2	Gitの`status`/`diff`/`commit`/`push`	AIの変更を確認し、戻せる形で進められる
Step 3	.env、秘密情報、.gitignore	漏洩リスクを避けられる
Step 4	Web/API、HTTP、JSON、Cookie/セッション	管理画面、LINE API、Webhookで何が起きているか追える
Step 5	DB、CRUD、SQL、migration、トランザクション	顧客データや配信履歴を壊さないための確認ができる
Step 6	テスト、ログ、ドライラン、E2E、ロールバック	「これで十分か」をAIに問い返せる
Step 7	セキュリティ、権限、XSS、SQLインジェクション	AIが危ない実装を出したときに止められる
Step 8	本番影響、外部連携、デプロイ	公開前の事故を減らせる

学ぶ順番: コードの文法より、変更管理、秘密情報、Web/API、DB、テスト、本番影響。ここを押さえると、AIの出力を「使ってよいか」判断できるようになります。

勉強のやり方

本や講座で全部を順番にやるより、今触っているrepoを題材にする。
分からない用語が出たら、AIに「このrepoのこのファイルを例に説明して」と頼む。
毎回「何が壊れうるか」「どう確認するか」「戻せるか」をセットで考える。
理解できないコードを無理に暗記せず、まず入力、出力、副作用、失敗時の動きを見る。

このファイルを教材にして、非エンジニア向けに説明して。入力、出力、外部サービス、DB、失敗時の動き、テストすべき場所に分けて。

15. 毎回使うチェックリスト

対象フォルダは1つに絞った
実装前に要件そのものの安全性を確認した
誤送、二重送信、対象者違い、QA/本番混同のリスクを確認した
これは本番・開発中・実験・素材のどれか分かっている
秘密情報の値をAIに読ませていない
Git状態を確認した
生成物と素材を混同していない
pushやdeployが起きる可能性を確認した
AIに削除・移動・修正をさせる前に、対象一覧を出させた
作業後に何が変わったか説明できる

16. 用語集

用語	平易な意味
repo / リポジトリ	Gitで管理されているプロジェクトフォルダ
dependency / 依存関係	そのアプリが動くために必要な外部ライブラリ
build	人間が書いたコードを公開・実行用に変換すること
deploy	サーバーやCloudflareなどに反映して、外から使える状態にすること
environment variable / 環境変数	アプリの外側から渡す設定値。秘密情報を入れることも多い
.env	環境変数をまとめて書くローカル設定ファイル。基本的にGitに入れない
NEXT_PUBLIC_	Next.jsでブラウザ側に見える可能性がある環境変数の接頭辞
.gitignore	Gitに入れないファイルを指定するリスト
migration	データベース構造を変更する作業。失敗すると影響が大きい
webhook	外部サービスから自動で通知・呼び出しされるURL