github-repo-restructure

name	github-repo-restructure
description	GitHubリポジトリのフォルダ構造を整理・移動し、README群を刷新する。 git clone → git mv → README作成 → git push の一括フローで確実に完了させる。 GitHub APIのPUT/DELETE単体でのファイル移動より大幅に信頼性が高い。
tags	["github","git","restructure","readme","documentation","folder","organize"]

GitHub リポジトリ構造整理スキル

いつ使うか

• フォルダ名を変更・統合・移動したい
• 散らかったルートを projects/ などのサブディレクトリに整理したい
• README群を相互リンク付きで刷新したい
• GitHub APIだけでやろうとしたが複雑だと感じたとき

---

手順

1. ローカルにクローン

cd /tmp && rm -rf repo_work
source /root/.hermes/profiles/bedrock-slack/.env
git clone https://<USER>:${GITHUB_HERMESSHIFT_PAT}@github.com/<ORG>/<REPO>.git repo_work
cd repo_work
git config user.email "[e-mail]"
git config user.name "Hermes Agent"

2. フォルダ移動（git mv を使うこと）

# 新しい親ディレクトリ作成
mkdir -p projects

# git mv でフォルダを移動（rename追跡が保持される）
git mv old_folder projects/new_folder

# 複数まとめて
git mv excelMCPserver       projects/excel_mcp_server/v1_basic
git mv excelMCPserverSPEC   projects/excel_mcp_server/v2_spec
git mv "excelMCPserverSPECFew-shot" projects/excel_mcp_server/v3_few_shot

⚠️ mkdir -p だけでは git はディレクトリを追跡しない。必ず git mv を使う。
⚠️ スペースや特殊文字を含むフォルダ名はクォートで囲む。

3. README を作成・更新

write_file ツールでローカルパスに直接書き込む：

/tmp/repo_work/README.md                        # ルートREADME（ナビゲーション）
/tmp/repo_work/projects/xxx/README.md           # 各プロジェクトREADME

ルートREADMEに含めるべき要素：

• リポジトリ概要
• フォルダ構成ツリー（tree形式）
• 環境構築手順テーブル（各ドキュメントへのリンク）
• プロジェクト一覧テーブル（リンク・概要・特徴）
• トラブルシューティング

プロジェクト比較READMEのパターン（複数バージョンがある場合）：

• バージョン間の発展経緯（v1 → v2 → v3 のアスキー図）
• 比較テーブル（観点 × バージョン）
• 推奨バージョンの使い方
• 上位READMEへの相対リンク

4. コミット＆プッシュ

cd /tmp/repo_work
git add -A
git status --short | head -20   # 確認
git commit -m "docs: フォルダ構造整理とREADME刷新"
git push origin main

---

ピットフォール

問題	解決
GitHub APIのPUT/DELETEで移動しようとすると複雑・SHAエラー多発	git clone → git mv → push で一括処理する
mkdir -p 後に git がディレクトリを認識しない	git mv を使うか、ファイルを置いてから git add する
移動後に相対リンクが壊れる	../../README.md など相対パスで記述し、移動先階層に合わせて調整
フォルダ名にスペース・ハイフンがある	git mv "old name" のようにクォートで囲む
コミット前に名前・メールが設定されていない	git config user.email / user.name を先に実行

---

README相互リンクのパターン

# プロジェクト名 — 概要

→ [詳細 README](projects/foo/README.md)         # ルートから子へ
→ [リポジトリ全体の README に戻る](../../README.md)  # 子からルートへ
→ [関連ドキュメント](../../doc/setup.md)          # 横断リンク

---

典型的なフォルダ整理パターン

Before:
  excelMCPserver/
  excelMCPserverSPEC/
  excelMCPserverSPECFew-shot/
  library_system/
  library_system_with_serena/
  library_system_with_superclaude/

After:
  projects/
    excel_mcp_server/
      v1_basic/         ← excelMCPserver
      v2_spec/          ← excelMCPserverSPEC
      v3_few_shot/      ← excelMCPserverSPECFew-shot
      README.md         ← 比較・全体解説
    library_system/
      v1_basic/         ← library_system
      v2_with_serena/   ← library_system_with_serena
      v3_with_superclaude/ ← library_system_with_superclaude
      README.md         ← 比較・全体解説