Claude Codeで既存リポジトリを修正する基本手順

Claude Codeで既存repositoryを直すなら、最初に変更を依頼するのではなく、作業場所・projectのルール・現在のGit状態・検証方法を確認します。これらが分からないまま編集を始めると、似た名前の別projectを触ったり、既存の未commit変更を上書きしたりするおそれがあります。安全な順序は「場所と状態→構造とrule→計画→小さな変更→検証→diff review」です。

AnthropicのCommon workflowsでは、codebaseの概要や関連fileを調べてから、errorの再現、変更、testへ進む例が案内されています。Claude Codeはfileを読んだりterminalを実行したりできますが、出力だけでproject全体を理解したと判断しないでください。根拠になったfileと、まだ確認していない範囲を分けて受け取ります。

最初に作業場所と変更前の状態を固定する

terminalから起動する場合は、修正したいrepositoryのrootへ移動してからClaude Codeを開始します。複数のcheckoutやworktreeを使っている場合は、directory名だけでなくbranchとremoteを確認します。作業を始める前に、status、変更file、必要なら直近commitを記録します。

表は横にスクロールできます

確認対象	見るもの	次へ進める条件
作業場所	repository root、現在のdirectory	対象repoと一致
Branch	branch名、HEAD	依頼の作業branchと一致
Working tree	tracked / untracked changes	既存WIPを把握し、上書きしない
実行方法	package scripts、README、CI	実際に存在するcommandを特定
制約	AGENTS.md、CLAUDE.md、その他rule	適用範囲と優先順位を把握

Git statusに未commit fileがある場合は、「Claude Codeが作ったもの」と決めつけず、今回の変更前から存在したかを確認します。触ってよいfileと変更禁止fileを分け、意図しないdiffを戻す判断はユーザーまたは既存運用ルールに従います。知らない変更を無条件にdiscardするのも、作業を続けて巻き込むのも避けます。

Codebase overviewは質問を段階的に絞る

最初に大まかな構造を聞き、その後、今回の変更に関係するentry point、data flow、testを確認します。Anthropicの公式workflowsも、新しいcodebaseでoverviewを得た後に具体componentを深掘りする方法を例示しています。

このrepositoryの構造を調べてください。最初に主要directoryとentry pointを説明し、今回の修正に関係するfileを列挙してください。各説明にはfile pathを付け、推測と確認済みの事実を分けてください。まだfileを変更しないでください。

回答にpathが出たら、そのfileが本当に存在するか、内容が現在のbranchにあるかを確認します。名前だけでなく、参照元から利用経路を追います。たとえばcomponentを見つけても、対象routeで使われているか、別のvariantが選ばれていないかを確認します。

表は横にスクロールできます

知りたいこと	質問例
Entry point	どのrouteまたはcommandからこの機能が始まりますか
Data flow	入力から画面表示まで、関係するfileを順に示してください
Existing pattern	同種の処理はどこにあり、何を再利用できますか
Test	仕様を確認するtestと実行commandはどれですか
Unknown	まだ実fileを読んでいない箇所はどこですか

CLAUDE.mdは指示、repositoryの実装は事実として読む

Claude Codeのmemory documentationによると、CLAUDE.mdやAGENTS.mdはsessionに継続的なproject contextを与える仕組みです。指示やruleとして役立ちますが、実際の実装と一致しているとは限りません。古いbuild commandや移動済みdirectoryが書かれていないか、package scriptやCIと照らします。

指示に複数ファイルを読むよう書かれている場合は、適用範囲と矛盾を整理します。たとえばrootのruleに「test必須」、特定directoryのruleに「このpackageではtestを省略」とあるなら、その適用範囲を確認します。機密情報を除外する設定も存在を確認しますが、除外されているfileを不用意に出力へ貼り付けたり、secretをpromptへ送ったりしません。

Planは変更範囲と戻しやすさを確認する

既存repoの修正は、要望をそのまま編集指示へする前に、変更候補と理由をplanにします。Claude CodeのPlan modeは、fileへ変更を加える前に分析と計画を行い、承認後に編集へ移るためのmodeとして公式Docsに説明されています。

目的は［期待するbehavior］です。変更候補file、既存pattern、必要なtest、影響するrouteを列挙してください。変更してよい範囲は［scope］、触らない範囲は［constraints］です。実装前に不明点とdata-loss riskを示し、まだ変更しないでください。

Planで見るのはfile数だけではありません。public API、URL、database、既存data、権限、生成file、広範囲なstyle等へ影響するかを確認します。小さなlocal bugなら実装前提を細かく増やさず、影響が広い場合だけ計画と確認を厚くします。

まずは使ってみる

記事の文脈に合うToolへ進めます。報酬の有無で見た目は変えていません。

• 

  Claude Code

  公式サイトを見るTool詳細を見る比較を見る

修正は最小単位で、確認方法と組み合わせる

Claude Codeが複数fileを編集できても、関連が薄いrefactorを同時に頼む必要はありません。原因のfile、関連するtest、必要なdocumentationに絞ります。初回は差分の小さい変更を選び、projectの命名やerror handlingに合わせます。

変更を頼む前に、以下を伝えます。

• 期待する動作と再現条件

• 変更してよいdirectoryと触らないfile

• 既存のWIPを保つこと

• 実行してよいcommand

• 修正後に確認するtest / lint / typecheck

• 完了時に返すdiff summaryと未確認項目

Anthropicのsecurity documentationは、file編集やcommand executionがpermissionに関わるactionであり、設定やapprovalによって制御されることを案内しています。作業しやすさだけを理由に、すべてのapprovalを無効にするのは避けます。repositoryの変更、外部通信、package installation、削除、deployのように影響の異なるcommandを同じ扱いにしないでください。

Terminalとpermissionの確認は作業前に行う

terminal commandを使う場合は、commandの目的と副作用を確認します。読み取りだけの調査、既存testの実行、format、依存追加、data migrationはリスクが異なります。Anthropicの権限設定ではtoolやcommandの許可・拒否を細かく扱えますが、個々の設定名やUIは更新される場合があります。現在の設定画面または公式Docsを確認し、記事では「permissionを広く開けばよい」と案内しません。

変更前に、実行予定command、対象file、書き込み・削除・networkの有無を説明してください。既存testとread-only調査を先に行い、dependency追加、data変更、外部送信、file削除、deployは実行前に止めてください。

実際にどこまで止まるかは、利用するClaude Code surface、設定、組織policyに依存します。重要な操作は、tool permissionだけに頼らず、利用者が実行内容とtargetを確認します。

検証は「通った」だけで終わらせない

修正後は、まず差分に対応したtestを実行し、次にprojectで要求される広いcheckへ進みます。もしtestが失敗したら、failureが今回の変更由来か既存failureかをbaselineと比較します。testのassertionを弱めてgreenにするのではなく、testが表す仕様と実装を照合します。

表は横にスクロールできます

確認	証拠	未確認のまま残す例
Typecheck	commandとexit result	command未実行
Unit / integration	対象caseのresult	外部serviceをmockしただけ
Build	build result、route生成数	dev server表示のみ
Runtime	API response、browser動作	実Production未確認
Security	permission・入力境界	threat model未確認

結果を報告させるときは、成功したcommand、対象範囲、失敗やskipped、手動確認が必要な点を分けます。toolが返した「成功しました」という自然文より、実行結果とdiffが証拠です。

Commit前に人が差分を読む

Claude CodeはGit commandを実行できますが、commitする前の最終責任は人に残します。statusとdiffで、変更fileが依頼と一致するか、untrackedや既存WIPが混ざっていないかを確認します。意図しない削除、lockfile、生成物、debug logging、secret、広いformat変更も見ます。

理由が説明できないfileは残しません。反対に、作業開始前からの変更を自分の修正と誤認して戻してはいけません。今回の作業と前からのWIPを区別したうえで、対象fileだけをcommitします。Production deployやmain mergeなどの外部操作は、branch上の修正完了とは別の明示gateです。

AIものさしの判断

既存repositoryでは、Claude Codeへいきなり変更を頼まず、場所・state・rule・検証方法を確かめてから始めると安全です。CLAUDE.mdは継続指示として読み、実装・script・testを別に照合します。小さな変更とその証拠を揃え、最後にdiffを人が確認できる状態にしてから次の作業へ進みます。permissionの設定名や機能は変わるため、具体的な初期値を固定せず、操作前に現行公式Docsを確認してください。