新しいリポジトリに入った最初の20分でやる初回点検チェックリスト

新しいプロジェクトに入った初日、僕はいきなり npm install を叩いて、そのまま開発サーバーを立ち上げました。

その瞬間、見覚えのない postinstall スクリプトが走って、ターミナルがよく分からないログで埋まったんです。あとで読んだら、外部のURLから何かをダウンロードしていました。悪意があったわけではなく、社内の古いツールでした。でも、中身を一度も見ずに自分のマシンで実行していた、という事実はゾッとしました。

リポジトリを渡されると、人はつい「早くコードを書きたい」と思います。でも、初対面の家に入ってすぐ冷蔵庫を開けないのと同じで、最初にやるべきは作業じゃなくて点検です。どこに地雷が埋まっているか、誰が掃除をサボっているか、それを20分で把握してから手を動かす。これだけで事故がごっそり減ります。

この記事は、新しいリポジトリに入った最初の20分でやる「初回点検チェックリスト」です。秘密情報の混入、依存の脆弱性、lint/CIの設定、権限、危険なスクリプト、ドキュメントの有無——この6つを順番に見ます。

この記事の要点

• 新しいリポジトリで最初に見るのはコードの中身ではなく6つの危険信号：秘密情報・依存の脆弱性・lint/CI・権限・危険スクリプト・ドキュメント。
• いちばん怖いのは package.json の postinstall など、install で勝手に走るスクリプト。読む前に npm install しない。
• 秘密情報は .env だけでなくコミット履歴の中にも残る。git log で消したつもりのキーが生きていることがある。
• 後半に、6点をまとめて吐き出すコピペで動く一括点検コマンドを置いた。Claude Codeに「これを実行して結果を要約して」と渡すと初回把握が一気に速くなる。
• 全体像の作り方は /blog/claude-code-existing-codebase-map、権限まわりの深掘りは /blog/claude-code-permission-audit-checklist へ。

なぜ「書く前に点検」なのか

理由はシンプルで、最初の install や最初の実行が、すでに取り返しのつかない操作だからです。

コードを1行書く前でも、依存をインストールした時点で他人の書いたスクリプトが自分のマシンで動きます。設定ファイルを読んだ時点で、エディタのプラグインがそれを解釈して何かを実行することもあります。つまり「まだ何もしていない」つもりでも、点検を飛ばした瞬間にもう手遅れになりうる。

もうひとつ、点検はそのプロジェクトの民度を測る作業でもあります。テストがあるか、CIが回っているか、READMEが現実と一致しているか。これを最初に見ておくと、「このコードベースはどのくらい信用していいか」の感覚が持てます。信用度が分かれば、自分がどこまで慎重に動くべきかも決まります。

Claude Codeに任せるときも同じです。AIは親切すぎる新人なので、何も言わなければ install も実行も平気でやります。だからこそ、人間が先に地図を作って「ここは触るな」を渡す。点検は、自分のためでもAIのためでもある下ごしらえなんです。

初回点検の6項目

僕が新しいリポジトリで必ず見る順番がこれです。上から順に、リスクが高くて見落としやすいものから並べています。

#	点検対象	最初に見る場所	何を確認するか
1	危険なスクリプト	package.json の scripts、Makefile	install で勝手に走る処理、rm -rf や本番への接続
2	秘密情報の混入	.env、.env.example、git log	実キーがコミットされていないか、履歴に残っていないか
3	依存の脆弱性	package-lock.json、audit	既知の脆弱性、古すぎる依存、放置されたパッケージ
4	lint / CI 設定	.github/workflows、eslint 設定	自動チェックが回っているか、壊れたまま放置でないか
5	権限・認証	auth、.env のスコープ、IAM	どこまでの権限を持つ鍵か、誰でも本番を触れる構成でないか
6	ドキュメント	README、CONTRIBUTING、docs/	起動手順が現実と合っているか、嘘が書かれていないか

ひとつずつ、何を見て何を警戒するかを書きます。

1. 危険なスクリプトを「実行する前に」読む

最優先はこれです。package.json の scripts を目で読む。特に preinstall / postinstall / prepare は、npm install を打った瞬間に走ります。中身を見ずにインストールするのは、知らない人が作った弁当を確認せず食べるようなものです。

Makefile やシェルスクリプトも同じ目で見ます。rm -rf がパスを変数で組み立てていたら、変数が空になった瞬間に rm -rf / になりかねません。本番のホスト名やDBの接続文字列が scripts に直書きされていないかも確認します。

2. 秘密情報は「履歴」まで疑う

.env がコミットされていないかは当然見ます。でも本当に怖いのはコミット履歴に残った鍵です。誰かが一度コミットして、あとで .gitignore に足しても、過去のコミットには残り続けます。「消したつもり」のAPIキーがいまも履歴の中で生きている、というのはよくある話です。

.env.example があるかも見ます。これがあると、どんな環境変数が必要かが分かり、逆に「example にない謎のキー」が混ざっていないかのチェックにもなります。

3. 依存の脆弱性とメンテ状況を見る

npm audit を回せば既知の脆弱性が出ます。数が多くても焦らず、high と critical だけ先に見ます。同時に、ロックファイルの更新日や、極端に古いメジャーバージョンの依存がないかも確認します。3年動いていないパッケージに依存していたら、それ自体がリスクです。

4. lint / CI が「生きているか」

.github/workflows を開いて、CIが回っているかを見ます。ファイルがあるだけでは不十分で、最近の実行が成功しているかまで見ます。赤いまま放置されたCIは、無いのと同じか、むしろ「誰も気にしていない」というサインです。lint設定があるなら、ローカルでも一度走らせて、既存コードがどのくらい設定を守っているかを確かめます。

5. 権限と認証の範囲

.env や設定にあるキーが、どこまでの権限を持つかを意識します。読み取り専用のキーと、本番DBを消せるキーでは、漏れたときの被害がまるで違います。誰でも本番環境に接続できる構成になっていないか、認証まわりの入口だけ先に押さえます。権限の点検は奥が深いので、専用の手順を /blog/claude-code-permission-audit-checklist にまとめました。

6. ドキュメントが現実と合っているか

最後にREADMEです。ただし「読む」のではなく「疑う」。書かれた起動手順をそのままなぞって、本当に動くかを見ます。READMEが古いプロジェクトは、コードも古いことが多い。CONTRIBUTING や docs/ があれば、チームのルール（ブランチ運用、レビュー方針）も先に拾っておきます。

実例：3タイプのリポジトリでの動き方

点検の重心は、リポジトリの種類で少し変わります。僕がよく入る3つで説明します。

Astroのような記事・LPサイト 危険スクリプトは少なめですが、postinstall で画像変換ツールを引いてくる構成はあります。秘密情報より、公開ビルドに混ざる設定（解析タグ、外部スクリプト）を先に見ます。点検後にコンテンツを触るなら、全体像の作り方を /blog/claude-code-existing-codebase-map で先に固めると安全です。

React管理画面 認証と権限が主役です。誰がどの画面を触れるか、本番APIのキーがフロントに埋まっていないか。.env のキーがビルドに焼き込まれる仕組み（VITE_ プレフィックスなど）は要注意で、公開バンドルに秘密が混ざりやすいポイントです。

APIリポジトリ DBマイグレーションと scripts がいちばん危険です。migrate 系のコマンドが本番を向いていないか、テストが本番DBを掃除する作りになっていないか。ここは読むだけにとどめ、実行は構成を理解してからにします。

コピペで動く：6点まとめて吐き出す一括点検コマンド

ここまでの6項目を、手で1つずつ確認するのは面倒です。そこで、初回点検の材料をまとめて出力するシェルスクリプトを置きます。Node系リポジトリの直下で実行してください。bash が動けばOK（WindowsならGit BashかWSL）。破壊的な操作は一切しません。読むだけです。

#!/usr/bin/env bash
# 初回リポジトリ点検：危険スクリプト/秘密情報/依存/CI/ドキュメントの材料を出力する。
# 何も書き換えず、何もインストールしない。読むだけ。
set -u

echo "===== 1. 危険なスクリプト（install で勝手に走るものに注意） ====="
if [ -f package.json ]; then
  # preinstall/postinstall/prepare は npm install 時に自動実行される
  node -e "const s=(require('./package.json').scripts)||{}; for(const k of Object.keys(s)){console.log((/^(pre|post)?install$|^prepare$/.test(k)?'⚠ ':'  ')+k+': '+s[k])}"
else
  echo "  package.json なし"
fi

echo
echo "===== 2. 秘密情報：追跡中の .env と、履歴に残った鍵らしき文字列 ====="
git ls-files | grep -E '(^|/)\.env($|\.)' | grep -v '\.example' || echo "  追跡中の .env は見当たらず（良い兆候）"
echo "-- コミット履歴から API キーらしき行を検索（30件まで） --"
git log -p -S 'API_KEY' --pickaxe-all 2>/dev/null | grep -iE '(api_key|secret|token|password)\s*[:=]' | head -n 30 || echo "  履歴に明らかな鍵は検出されず"

echo
echo "===== 3. 依存の脆弱性（high と critical のみ要約） ====="
if [ -f package-lock.json ]; then
  npm audit --omit=dev 2>/dev/null | grep -E 'high|critical|vulnerabilit' | head -n 20 || echo "  audit で high/critical は出ず、または audit 未対応"
else
  echo "  package-lock.json なし（npm ci できない可能性）"
fi

echo
echo "===== 4. lint / CI 設定の有無 ====="
ls -1 .github/workflows 2>/dev/null || echo "  GitHub Actions のワークフローなし"
ls -1 .eslintrc* eslint.config.* .prettierrc* 2>/dev/null || echo "  lint/format 設定が見当たらず"

echo
echo "===== 5. ドキュメントの有無と鮮度 ====="
for f in README.md CONTRIBUTING.md SECURITY.md docs; do
  if [ -e "$f" ]; then
    echo "  あり: $f （最終更新: $(git log -1 --format=%cs -- "$f" 2>/dev/null)）"
  else
    echo "  なし: $f"
  fi
done

echo
echo "点検完了。⚠ が付いた行と、5の最終更新日が古いものを先に疑うこと。"

このスクリプトの狙いは、判断材料を一画面に集めることです。巨大なレポートを作るのが目的ではありません。⚠ が付いた install 系スクリプト、履歴に残った鍵、high/critical の脆弱性、更新日が古いドキュメント——この4つが「先に疑う場所」になります。

Claude Codeを使っているなら、このスクリプトを保存して bash audit.sh と実行し、出力を貼って「危険そうな順に3つ挙げて、それぞれ何が問題か説明して」と頼むと、初回把握が一気に速くなります。点検の結果をもとに「触ってよいファイル」を決めてから、初めて編集に入ってください。

よくある質問

Q. 点検は本当に20分で終わりますか？ A. 中規模までのリポジトリなら終わります。上のスクリプトを1回流せば、危険スクリプト・秘密情報・依存・CI・ドキュメントの材料は数十秒で出ます。残りの時間は、出てきた ⚠ と古いドキュメントを目で追うのに使います。巨大なモノレポなら、まず触る予定のパッケージ1つに絞れば20分に収まります。

Q. npm install は点検が終わるまで本当に我慢すべき？ A. はい。少なくとも package.json の scripts を目で読むまでは待ってください。postinstall を確認すれば、何が走るか分かります。どうしても先に依存が必要なら、隔離した環境（コンテナや使い捨てVM）で実行します。

Q. 秘密情報がコミット履歴に残っていたら、どうすればいい？ A. まず**その鍵を無効化（ローテーション）**してください。履歴から消すより先です。生きている鍵を放置したまま履歴だけ書き換えても、漏れた事実は変わりません。無効化してから、必要なら履歴の書き換えを検討します。

Q. npm audit で大量に警告が出て心が折れます。 A. 最初は high と critical だけ見れば十分です。--omit=dev を付けると本番に効く依存に絞れます。全部を一度に直そうとせず、まず本番影響のあるものから1つずつ潰します。

Q. Claude Codeにこの点検そのものを任せていい？ A. 「読むだけ」の点検なら任せて大丈夫です。ただし最初に「インストールや実行はしないで、まず読んで報告して」と明示してください。範囲を渡さないとAIは親切心で install まで進めます。権限の渡し方は /blog/claude-code-permission-audit-checklist が参考になります。

実際に試した結果

冒頭の postinstall 事件以来、僕は新しいリポジトリで真っ先にやることを変えました。コードを開く前に、上のスクリプトを1回流す。それだけです。

効果は地味だけどはっきり出ました。あるプロジェクトでは、履歴に古いAWSの一時キーが残っているのを初日に見つけて、その場でローテーションを依頼できました。別のリポジトリでは、CIが3か月前から赤いまま放置されているのに気づき、「このチームはテストを信用していない」と早めに察知できた。どちらも、点検を飛ばしていたら数週間は気づかなかったはずです。

新しいコードベースで早く成果を出すコツは、速くコードを書くことではなく、地雷の位置を先に知ることでした。20分の点検は、初日の焦りに対するいちばん効く保険です。点検が終わったら、次は全体像の作り方を /blog/claude-code-existing-codebase-map で固めると、編集まで一直線につながります。

ここまでの手順を実務で型にしたい人は 研修・相談 でも具体例を扱っています。公式の npm audit の挙動は npmのドキュメント で確認できます。