開発トラブルシューティング
安全なファイル編集ガイドライン
AIアシスタント向けの安全なファイル編集・破損防止ガイドライン
安全なファイル編集ガイドライン
最終更新: 2025-12-06
対象: AIアシスタント
目的: ファイル編集時の破損を防止し、安全で確実な編集を実現する
1. 問題の背景
1.1 発生する問題
AIアシスタントがファイル編集ツール（replace_file_content, multi_replace_file_content）を使用する際、以下の問題が頻繁に発生しています：
- TargetContentの不一致: 改行コード（CRLF vs LF）、空白文字、特殊文字の違いにより、意図した箇所が検出されない
- ファイル構造の破損: 編集が部分的に適用され、ファイルの構造が壊れる
- 重要な情報の喪失: セクション全体が削除されたり、テーブル構造が崩れたりする
1.2 根本原因
- 改行コードの不一致: Windows環境では
\r\n(CRLF)、Unix/Mac環境では\n(LF)が使用される - 見えない文字: タブ、全角スペース、ゼロ幅スペースなどの存在
- ツールの制約:
TargetContentは完全一致を要求するため、わずかな差異でも失敗する - 複雑な編集の試み: 大きなブロックを一度に置換しようとすると失敗しやすい
2. 安全なファイル編集の原則
原則1: 最小単位での編集
❌ 悪い例: 大きなセクション全体を置換
TargetContent: "## 3. フロントエンド\n\n| カテゴリ | ... (50行) ... |"✅ 良い例: 1-2行ずつ追加・修正
TargetContent: "| **汎用フック** | [react-use](...) | ... |\n"
ReplacementContent: "| **汎用フック** | [react-use](...) | ... |\n| **画像ライトボックス** | ... |\n"原則2: 改行コードに依存しない編集
❌ 悪い例: 改行コードを含むTargetContent
TargetContent: "line1\nline2\nline3" # LFを仮定✅ 良い例: 単一行の編集、または行番号範囲の指定
StartLine: 50
EndLine: 50
TargetContent: "| **汎用フック** | [react-use](...) | ... |"原則3: 重要ファイルは慎重に
重要度の高いファイル（システムドキュメント、設定ファイルなど）を編集する際は：
- 事前確認:
view_fileで現在の内容を正確に把握 - 小さな変更: 一度に1つの変更のみを適用
- 検証: 編集後に
view_fileで結果を確認 - バックアップ意識: Git管理されていることを前提とし、必要に応じて
git checkoutで復元可能であることを確認
原則4: 失敗時の対処
編集が失敗した場合：
- 即座に停止: 連続して同じ編集を試みない
- 原因分析:
view_fileで現在の状態を確認 - 代替手段:
- より小さな単位に分割
write_to_fileでファイル全体を書き換え（小さなファイルの場合）- ユーザーに手動編集を依頼
3. 実践的な編集戦略
戦略A: 行末への追加（最も安全）
使用場面: テーブルやリストに新しいエントリを追加する場合
手順:
- 追加したい位置の直前の行を特定
- その行全体を
TargetContentに設定 ReplacementContentに元の行 + 改行 + 新しい行を設定
例:
TargetContent: "| **汎用フック** | [react-use](https://github.com/streamich/react-use) | センサー、UI、アニメーションなど、多岐にわたる便利なカスタムフックを提供するライブラリ。Exploreページで画面幅を取得する`useWindowSize`フックを利用。 |"
ReplacementContent: "| **汎用フック** | [react-use](https://github.com/streamich/react-use) | センサー、UI、アニメーションなど、多岐にわたる便利なカスタムフックを提供するライブラリ。Exploreページで画面幅を取得する`useWindowSize`フックを利用。 |\n| **画像ライトボックス** | [yet-another-react-lightbox](https://yet-another-react-lightbox.com/) | モダンでアクセシブルなReact用Lightboxコンポーネント。 |"戦略B: 行番号範囲指定（推奨）
使用場面: 特定の行を修正する場合
手順:
view_fileで対象行の行番号を確認StartLineとEndLineで範囲を指定- その範囲内の正確な内容を
TargetContentに設定
例:
StartLine: 50
EndLine: 50
TargetContent: "| **汎用フック** | [react-use](https://github.com/streamich/react-use) | センサー、UI、アニメーションなど、多岐にわたる便利なカスタムフックを提供するライブラリ。Exploreページで画面幅を取得する`useWindowSize`フックを利用。 |"
ReplacementContent: "| **汎用フック** | [react-use](https://github.com/streamich/react-use) | センサー、UI、アニメーションなど、多岐にわたる便利なカスタムフックを提供するライブラリ。Exploreページで画面幅を取得する`useWindowSize`フックを利用。 |\n| **画像ライトボックス** | [yet-another-react-lightbox](https://yet-another-react-lightbox.com/) | モダンでアクセシブルなReact用Lightboxコンポーネント。 |"戦略C: ファイル全体の書き換え（小規模ファイル限定）
使用場面:
- ファイルが小さい（100行未満）
- 複数箇所を同時に編集する必要がある
- 他の方法で失敗した場合
手順:
view_fileで全内容を取得- 内容全体をコピーして修正
write_to_fileでOverwrite=trueとして書き込み
注意: この方法は最後の手段として使用すること
4. チェックリスト
編集前に以下を確認してください：
-
view_fileで現在の内容を確認した - 編集範囲は最小限（1-3行程度）に抑えている
-
TargetContentはview_fileの出力から正確にコピーした - 改行コードや特殊文字に注意を払った
-
StartLineとEndLineを適切に設定した（該当する場合） - 重要ファイルの場合、バックアップ方法を確認した
編集後に以下を確認してください：
- 編集が成功したことをツールの出力で確認した
-
view_fileで結果を検証した - ファイル構造が破損していないことを確認した
- 意図しない変更が含まれていないことを確認した
5. 失敗例と対策
例1: Markdownテーブルの編集失敗
失敗した編集:
TargetContent: "| カテゴリ | ライブラリ | 説明 |\n| --- | --- | --- |\n| **A** | ... |\n| **B** | ... |"問題: 複数行にわたる編集で、改行コードの不一致により失敗
対策: 最後の行のみを対象にする
TargetContent: "| **B** | ... |"
ReplacementContent: "| **B** | ... |\n| **C** | ... |"例2: セクション全体の置換失敗
失敗した編集:
TargetContent: "## 3. フロントエンド\n\n(50行のテーブル全体)"問題: 大きすぎるブロックの置換
対策: セクション内の特定の行のみを編集するか、write_to_fileでファイル全体を書き換え
6. 推奨ワークフロー
1. view_file で対象ファイルの内容を確認
↓
2. 編集箇所を特定（行番号をメモ）
↓
3. 最小単位の編集を計画
↓
4. replace_file_content を実行
↓
5. 成功を確認
↓
6. view_file で結果を検証
↓
7. 失敗した場合:
- より小さな単位に分割
- 別の戦略を試す
- ユーザーに報告・相談7. 緊急時の復旧手順
ファイルが破損した場合：
- 即座に停止: それ以上の編集を行わない
- ユーザーに報告: 破損の事実と範囲を明確に伝える
- Git復元を提案:
git checkout HEAD -- <ファイルパス>で復元 - 代替案の提示: 手動編集が必要な内容を明確に提示
8. まとめ
最重要原則:
- 小さく、確実に編集する
- 改行コードに依存しない
- 常に検証する
- 失敗したら停止し、別の方法を考える
このガイドラインに従うことで、ファイル破損のリスクを大幅に低減できます。
関連ドキュメント:
document_maintenance.md: ドキュメント整備の全体的なガイドラインdocument_architecture.md: ドキュメント体系の設計思想