.gitignore typo修正とAstroビルド生成物のuntrack化による作業ツリーの整理

背景と解決する課題

データ分析プロジェクトやAI駆動開発において、git statusの出力が不要なファイルで汚染されると、Claude Code等のAIエージェントが状況を正確に把握できず、作業効率が大幅に低下します。

この記事では、analytics_noteリポジトリで発生した2つのGit管理ノイズ（.gitignoreのtypoと、Astroビルド生成物のtracking）を解決した実装手順を解説します。同様の問題を抱えるプロジェクトの参考になる、完全に再現可能な手順を提供します。

課題の詳細分析

課題1: .gitignoreのスプリントディレクトリパターンtypo

問題の状況:

現在の記述: .claude/sprint/（単数形）
実際のディレクトリ: .claude/sprints/sprint-xxx/（複数形）
結果: /implement skill実行時のプロンプトログが毎回untrackedとして残る

技術的制約:

.claude/sprints/*.jsonはスプリントメタデータとして意図的にtracked
.claude/sprints/全体をignoreするのは不適切
サブディレクトリのみをignoreする必要: .claude/sprints/sprint-*/

課題2: Astroビルド生成物のトラッキング方針不統一

現状の問題:

tracked: collections/blog.schema.json, content-assets.mjs など5ファイル
astro build実行のたびに順序差だけのdiffが発生
生成物をGitで管理する必要性がない（CIで毎回ビルドされるため）

実装手順

手順1: .gitignoreのtypo修正

# 現在の.gitignoreを確認
grep -n "sprint" .gitignore

# typoの修正
sed -i 's/\.claude\/sprint\//\.claude\/sprints\/sprint-*\//' .gitignore

手順2: Astroビルド生成物のuntrack化

# 既存のtrackedファイルをuntrack（但しローカルには残す）
git rm --cached -r apps/site/.astro/

# .gitignoreに追加
echo "apps/site/.astro/" >> .gitignore

重要な注意点:

git rm --cachedと.gitignore更新は同一コミットで原子的に実行
先にrmだけすると次回ビルドで再コミットされる可能性

手順3: 動作検証

# ビルドが正常に通ることを確認
pnpm --filter @analytics-note/site build

# git statusがcleanであることを確認
git status

# 新しいスプリント実行時のテスト
# （実際のスプリント実行で検証が必要）

完了条件と検証方法

検証項目

gitignore効果の確認:

# clean状態でビルド後もdiffが出ない
git status
pnpm build
git status  # Still clean

スプリントディレクトリの確認:

# 新しいスプリント実行後
ls -la .claude/sprints/
git status  # sprint-*/内のファイルが表示されない

CI/CD パイプラインの確認:
- deploy-site.ymlが正常に実行される
- Astroのビルドプロセスが影響を受けない

トラブルシューティング

よくある問題と対処法

問題: ビルド後にまだdiffが出る

# .gitignoreの効果を確認
git check-ignore apps/site/.astro/types.d.ts
# 出力があればignoreされている

問題: CIでビルドが失敗する

Astroは必要なファイルを自動生成するため、通常は問題なし
エラーが出る場合は依存関係の確認が必要

セキュリティとベストプラクティス

.gitignoreパターンの設計原則

生成物は基本的にuntrack: ビルドツールが生成するファイルはGitで管理しない
メタデータは例外的にtrack: スプリントのJSONのように、ツール連携で必要なデータは管理下に置く
パターンの具体性: *よりsprint-*/のように具体的なパターンを使用

参考リソース

この記事と関連する開発ワークフローの改善記事：

まとめ

.gitignoreの適切な管理により、AI駆動開発における認知負荷を大幅に削減できます。特に：

typoの修正: パターンマッチングが正確に動作
生成物のuntrack: ビルドのたびのdiffノイズを除去
原子的なコミット: 中途半端な状態を作らない安全な更新

これらの改善により、git statusが常にクリーンな状態を保ち、AI エージェントが適切に状況を把握できる環境を構築できました。