Dotfiles

Dotfiles

100倍のスループットを実現する AI エージェントのオーケストレーション基盤。あらゆるハーネス（Claude Code、Amazon Q、Codex）でエージェントを並列化し、再現可能な設定によって原則を徹底し、開発スタックを自己修復します。

Dotfiles の哲学

私たちの dotfiles リポジトリは、設定管理へのアプローチを導く 3 つの核となる原則に従っています。

コーヒーをこぼす原則

「コーヒーをこぼす原則」とは、誰でも自分のマシンを破壊しても、その日の午後には完全に稼働できる状態に戻せるべきだという考え方です。この原則は次を重視します。

• すべての設定変更は、マシン間で再現可能であるべき
• セットアップスクリプトは、手動コマンドではなくファイル操作を処理すべき
• インストールスクリプトは、必要なディレクトリを検出して作成すべき
• シンボリックリンクは、手動でのリンクではなくセットアップスクリプトで管理すべき
• 依存関係とインストール手順は、十分に文書化されているべき

❌ よくある違反 - 手動ターミナルヒロイックス:

The Phoenix Project の Brent のように、私たちはしばしば手動で問題を修正する「頼れるヒーロー」となってボトルネックになります。これらのコマンドはスクリプト内ではまったく有効ですが、ターミナルに直接入力するとアンチパターンになります。

# IN TERMINAL (BAD - Makes you Brent, the bottleneck hero):
dotfiles (main) $ ln -s mcp/mcp.json .mcp.json      # Works today, forgotten tomorrow
dotfiles (main) $ mv .bashrc .bashrc.backup          # Your knowledge, lost when you leave
dotfiles (main) $ chmod 600 ~/.bash_secrets          # New teammate: "Why doesn't this work?"
dotfiles (main) $ mkdir -p ~/ppv/pillars             # "It worked on my machine..."
dotfiles (main) $ echo "alias q='q'" >> ~/.bashrc   # Snowflake environment alert!
dotfiles (main) $ curl -o tool.tar.gz https://...    # Downloaded where? What version?

# The exact violation that inspired this documentation:
dotfiles (feature/vendor-agnostic-mcp-692) $ ln -s mcp/mcp.json .mcp.json
# ↑ I actually did this! Then immediately undid it and wrote a script instead.

Brent テスト: もしあなたがバスにひかれたら（あるいは休暇を取ったら）、他の誰かがあなたのやったことを再現できるでしょうか？それがあなたのターミナル履歴にしか残っていないなら、あなたは Brent になっています。

✅ スクリプト内の同じコマンド（GOOD - もう Brent はいない！）:

# IN SCRIPTS (GOOD - Knowledge is codified, not tribal):

# setup-vendor-agnostic-mcp.sh
ln -s mcp/mcp.json "$REPO_ROOT/.mcp.json"  # Reproducible by anyone

# setup.sh  
mkdir -p "$HOME/ppv/pillars"                # Self-documenting
chmod 600 ~/.bash_secrets                   # Security automated

# install-tool.sh
download_and_install_tool() {
    curl -o "$TEMP_DIR/tool.tar.gz" https://...  # Version controlled
}

The Phoenix Principle: 「Brent がやった」から「システムがやる」へ移行しましょう。状態を変更するすべてのターミナルコマンドはコードになり、キーパーソンへの依存を取り除くべきです。

リトマス試験: あなたはラップトップを破壊し、新しいものを手に入れ、git clone && ./setup.sh を実行して、まったく同じ状態に戻れるでしょうか？もしできないなら、あなたはスチュワードではなくヒーローになっています。

この原則は、システム障害からの復旧や新しい環境のセットアップにおける耐障害性と迅速な復旧を保証します。

スノーボールメソッド

スノーボールメソッドを参照してください - 日々の成果を積み重ねることで複利効果を得ます。この原則は、毎日 1% ずつ改善することで、私たちの開発環境が時間とともに継続的に向上することを保証します。

エージェントオーケストレーション基盤

このシステムは、IDE 内でコードの行を編集するマイクロレベルの作業ではなく、マクロレベルのエージェント管理を可能にします - あなたはコードの行ではなく、タスクとプロジェクトを管理します。中核となる基盤は次のとおりです。

• ハーネス非依存の設定: 単一の .agent-config.yml がユーザー設定、エージェント設定、パスを定義し、重複なしで Claude Code、Amazon Q、Codex 全体で動作します（config-architecture.mdを参照）
• 再現可能なエージェント手順: commands/ ディレクトリ内のスラッシュコマンド（/close-issue、/create-issue、/extract-best-frame、/retro）が、すべての AI ハーネス全体で一貫したワークフローを徹底します
• テレメトリとフィードバック: Grafana ダッシュボードを備えた OpenTelemetry オブザーバビリティスタックが、リアルタイムのパフォーマンス監視と継続的改善の洞察を提供します（observability/README.mdを参照）
• 並列実行: tmux + git worktreesを使用して、並列タスク全体で複数の AI エージェントを同時に管理します
• 原則の徹底: knowledge/procedures/ と knowledge/principles/ がエージェントのコンテキストに自動的に読み込まれ、一貫性を維持します

目標: AI エージェント管理能力を通じて、開発者の生産性を 100 倍から 1000 倍にすること。スループットの定義を参照してください。

モジュール式シェル設定

このリポジトリは、シェル設定に対してモジュール式のアプローチを採用しています。

# Load modular alias files from .bash_aliases.d directory
if [ -d "$HOME/.bash_aliases.d" ]; then
  for module in "$HOME/.bash_aliases.d"/*.sh; do
    if [ -f "$module" ]; then
      source "$module"
    fi
  done
fi

このパターンは次を提供します。

• 関心の分離 – 各ファイルは特定のツールに焦点を当てます
• 遅延読み込み – ファイルは存在する場合にのみ source されます
• 名前空間の衛生 – グローバル名前空間を散らかすのを避けます

モジュールは .bash_aliases.d/<tool-name>.sh に保存され、存在する場合は自動的に読み込まれます。

組織のコンテキスト: P.P.V システム

このリポジトリは通常 ~/ppv/pillars/dotfiles/ に配置され、3 層の組織システムの一部として機能します:

• Pillars: コアリポジトリと基盤となる設定 (ここが該当します)
• Pipelines: 自動化スクリプトとワークフローのリポジトリ
• Vaults: 認証情報や会社固有の属人的なナレッジを安全に保管する場所

この構造は、プロジェクトや環境全体で一貫したレイアウトを維持しつつ、関心事を分離します。

システム作業における 80/20 の法則

The Pragmatic Programmer の「Remember the Big Picture」に従いましょう - システムの最適化に没頭しすぎて、本来の作業の勢いを失わないようにします:

• 80% の作業: システムの統合、自動化 (Spilled Coffee 原則)、エージェントのオーケストレーション
• 20% のシステム最適化: 設定の調整、ワークフローの最適化、メタ作業

目標は、作業を可能にするシステムであり、システムそのものを目的にすることではありません。インフラの改善と実際の価値の提供のバランスを取りましょう。

グローバルファーストの設定

この原則は、dotfiles 内の設定は、明示的に別段の指定がない限り、デフォルトでグローバルに適用されるべきであることを定めています。これは、dotfiles リポジトリの根本的な目的 - システム全体で一貫した設定を提供すること - と一致します。

中核原則: 機能を実装する際は、ローカルよりもグローバルな設定を優先します。dotfiles はグローバルな設定のためのものです。

実装ガイドライン:

• デフォルト: 設定をグローバル (システム全体) にします
• 例外: 設定をローカルにしなければならない場合は、その理由を文書化し、グローバル化するための計画を追加します
• パターン: エイリアス、シンボリックリンク、またはツール固有のグローバル設定場所を使用します

例:

• ✅ --mcp-config を指定した claude エイリアスによる MCP 設定 (デフォルトでグローバル)
• ✅ ~/.bashrc から読み込まれる Bash エイリアス (どこでも適用)
• ⚠️ Claude Code 設定の ~/.claude/settings.json への移行 (作業中、#577 を参照)

ドキュメントの区別:

• README.md: リポジトリ固有のドキュメントと原則 (このファイル)
• knowledge/ ディレクトリ: すべてのリポジトリに適用されるグローバルなコンテキスト
  • AI アシスタントのコンテキストウィンドウに自動的に含まれます
  • どこでも使われる原則、手順、パターンを含みます
  • あなたとともに移動する「ポータブルな知恵」と考えてください

迷ったときは、こう問いかけてください: 「これはコーディングするすべての場所に適用されるべきか?」 はいなら → グローバルな設定です。これがこの dotfiles リポジトリの仕組みに固有のものであるなら → ここ README.md に文書化します。

リポジトリの設計パターン

このリポジトリは、一貫性と明確さを維持するために特定の組織パターンに従っています:

プラットフォームベースの構成 (トップレベル)

ルートレベルでは、設定はプラットフォームまたは環境ごとに整理されています:

• arch-linux/ - Arch Linux システム固有の設定
• raspberry-pi/ - Raspberry Pi デバイス向けの設定
• nvim/ - テキストエディタの設定 (レガシー/任意)
• など

この構造的な整理により、どのファイルがどの環境に適用されるかが明確になります。

ハイブリッドな構成 (プラットフォーム内)

各プラットフォームディレクトリ内では、カテゴリと具体的なユースケースを組み合わせたハイブリッドなアプローチを採用しています:

raspberry-pi/
├── home/                  # Home use cases
│   ├── home-assistant/    # Smart home hub
│   └── media-server/      # Media streaming
├── development/           # Development use cases
│   └── ci-runner/         # Self-hosted CI/CD
└── networking/            # Networking use cases
    └── network-monitor/   # Traffic analysis

このアプローチは:

• 保守性のために一般的なカテゴリで整理します
• 明確さのために具体的な例を提供します
• ユーザーが想定するユースケースに基づいて設定を見つけられるようにします

機能ベースの実装

機能の実際の実装は、以下の原則に従います:

1. 想定ではなく検出: スクリプトは特定のユースケースを想定するのではなく、ハードウェアの機能を検出します
2. コンポーザビリティ: 機能はユーザーのニーズに応じて組み合わせたり、組み替えたりできます
3. 自動最適化: ハードウェア固有の最適化が自動的に適用されます
4. 明確なドキュメント: 各機能はその目的と要件を文書化します

この多層的な構成アプローチにより、クリーンなリポジトリ構造を維持しつつ、さまざまなユースケースに柔軟に対応できます。

クイックセットアップ

ドットファイルをセットアップする

パーソナライズされた環境を使い始めましょう:

# Clone the repository and run setup
git clone https://github.com/atxtechbro/dotfiles.git ~/ppv/pillars/dotfiles
cd ~/ppv/pillars/dotfiles
source setup.sh

セットアップスクリプトは以下を自動的に処理します:

• パッケージのインストールと依存関係の管理
• 必要なすべてのシンボリックリンクの作成
• テンプレートからのシークレットファイルのセットアップ
• 設定の即時適用
• 必須ツール (tmux、Amazon Q CLI、GitHub CLI など) のインストールと設定

「Spilled Coffee Principle」に従い、セットアップスクリプトは一度実行するだけで完全に運用可能な状態になることを保証します。

カスタムクローン場所

デフォルトでは、これらのドットファイルは ~/ppv/pillars/dotfiles にクローンすることを前提としています。別の場所 (例: ~/dotfiles や ~/code/dotfiles) にクローンしたい場合は、source setup.sh を実行する前に ~/.bash_exports.local で DOT_DEN 環境変数を設定してください:

# Clone to your preferred location
git clone https://github.com/atxtechbro/dotfiles.git ~/my/custom/path

# Create ~/.bash_exports.local with your custom path
echo 'export DOT_DEN="$HOME/my/custom/path"' >> ~/.bash_exports.local

# Now run setup
cd ~/my/custom/path
source setup.sh

~/.bash_exports.local ファイルは git で追跡されていない (マシン固有である) ため、各マシンが独自のクローン場所を持つことができます。このファイルを作成しない場合は、デフォルトの ~/ppv/pillars/dotfiles が使用されます。

Worktree による並行開発

複数の機能を同時に作業するために、git worktree をサポートしています:

# Create a new worktree for your feature
cd ~/ppv/pillars/dotfiles
git worktree add -b feature/my-feature worktrees/feature/my-feature

# Set up the worktree environment
cd worktrees/feature/my-feature
source setup.sh

各 worktree は、独自の MCP サーバー、バイナリ、依存関係を備えた自己完結型です。詳細な手順については docs/worktree-development.md を参照してください。

AI ハーネス非依存のコンテキスト

このリポジトリは、単一の信頼できる情報源から複数の AI 開発ハーネス用のグローバルコンテキストを自動的に設定します:

• Amazon Q Developer CLI: 自動 MCP インポートを使用 (q mcp import --file mcp/mcp.json global --force)
• Claude Code: 直接的な設定参照を使用 (--mcp-config mcp/mcp.json)

すべてのコンテキストは knowledge/ ディレクトリから取得され、MCP サーバーはハーネス間で同一に設定されます。

ハーネスの対称性

両方の AI ハーネスは、異なる統合方法を通じて同一の MCP サーバー設定を使用します:

# Single source of truth
GLOBAL_MCP_CONFIG="$DOT_DEN/mcp/mcp.json"

# Claude Code: Direct file reference
alias claude='claude --mcp-config "$GLOBAL_MCP_CONFIG" --add-dir "$DOT_DEN/knowledge"'

# Amazon Q: Automatic import
alias q='q mcp import --file "$GLOBAL_MCP_CONFIG" global --force >/dev/null 2>&1; command q'

危機耐性: Claude Code が 500 の「Overloaded」エラーに遭遇した場合、Amazon Q が同一の MCP サーバーアクセスと機能を提供します。このハーネス非依存性により、サービス障害時でもワークフローが中断されないことが保証されます。

利用可能な MCP サーバー: 両方のハーネスが git 操作、GitHub 統合、ファイルシステム操作、knowledge ディレクトリのコンテキスト、および作業固有のサーバー (WORK_MACHINE=true の場合) にアクセスできます。

Claude Code の設定

グローバルな Claude Code 設定は .claude/settings.json を通じて管理されます。このファイルはセットアップスクリプトによって ~/.claude/settings.json にシンボリックリンクされ、すべてのプロジェクトで設定が保持されることを保証します。

Claude Code 設定を追加または変更するには:

1. ドットファイルリポジトリの .claude/settings.json を編集します
2. source setup.sh を実行してシンボリックリンクを更新します
3. 設定はすべての Claude Code セッションにグローバルに適用されます

現在設定されている項目には、共同著作権表示、MCP サーバー、権限などが含まれます。

Claude Code プラグイン

Claude Code のプラグインシステムを通じて、リポジトリ間でスラッシュコマンドを共有できます。

コマンド: /close-issue、/create-issue、/extract-best-frame、/retro

インストール (Claude Code のチャット内で):

/plugin marketplace add atxtechbro/dotfiles
/plugin install dotfiles-commands@atxtechbro

その後 Claude Code を再起動してください。コマンドがオートコンプリートに表示されるようになります。

コマンドは単一の信頼できる情報源として knowledge/procedures/ にシンボリックリンクされます。

グローバル MCP 設定

ドットファイルは、システム上の任意のディレクトリから MCP (Model Context Protocol) サーバーへのグローバルアクセスを提供します。source setup.sh を実行すると、MCP サーバーは claude コマンドエイリアスを通じて自動的に利用可能になります。

仕組み

1. 一元設定: MCP サーバーは mcp/mcp.json で定義されています
2. グローバルエイリアス: claude コマンドは自動的に --mcp-config を含むようにエイリアスされています
3. どこでも動作: 各プロジェクトディレクトリに .mcp.json ファイルをコピーする必要はありません

利用可能なコマンド

# Standard claude command (includes global MCP config automatically)
claude "What files are in this directory?"

# Check current MCP configuration
claude-mcp-info

# Use strict global config (ignores any local .mcp.json files)
claude-global "Run a command with only global MCP servers"

# Add user-scoped servers (persists across all projects)
claude mcp add my-server -s user /path/to/server

含まれる MCP サーバー

ドットファイルには、以下用の事前設定された MCP サーバーが含まれています:

• Playwright ブラウザ自動化 (ブラウザ操作が必要なタスク用)

注: Git、GitHub、Web 検索は Claude Code によってネイティブに処理されます (実験 #1213)

Claude モデルの設定

個人用マシンでは、最大限の能力を引き出すために Opus モデル（claude-opus-4-20250514）が自動的に使用されます。これは WORK_MACHINE 環境変数で制御します。

• 個人用マシン: ~/.bash_exports.local に WORK_MACHINE="false" を設定 → デフォルトで Opus モデル
• 仕事用マシン: WORK_MACHINE="true" を設定 → 標準のモデル選択

手動でモデルを切り替える必要はありません。マシンの種類に応じて適切なモデルが自動的に選択されます。

シークレット管理

API トークンなどの機密情報は ~/.bash_secrets に保存されます（git では追跡されません）。

# Create your personal secrets file from the example template
cp ~/ppv/pillars/dotfiles/.bash_secrets.example ~/.bash_secrets

# Set proper permissions to protect your secrets
chmod 600 ~/.bash_secrets

# Edit the file to add your specific secrets
nano ~/.bash_secrets

.bash_secrets ファイルは .bashrc によって自動的に読み込まれます。シークレットと環境変数を管理するためのフレームワークを一般的なパターンの例とともに提供します。必要に応じてカスタマイズしてください。

会社固有のシークレットについては、Vaults ディレクトリに別のプライベートリポジトリを維持することを検討してください。