Imported from happy663/dotfiles (
AGENTS.md). Install upstream withnpx skills add happy663/dotfiles. Copyright stays with the author.
AGENTS.md - dotfiles
このファイルは、このリポジトリで作業するコーディングエージェント向けの指示です。
Claude Code の CLAUDE.md からも @AGENTS.md で参照される、プロジェクト共通指示の集約元です。
Scope: このディレクトリ配下すべて。
Project Overview
- 個人開発環境を宣言的に管理する dotfiles プロジェクト。
- 対応プラットフォーム:
- macOS (Apple Silicon)
- Linux (x86_64)
- 主要スタック:
- Nix + Home Manager（環境の宣言的管理）
- nix-darwin（macOS 固有設定）
- 30 以上のツール設定を
conf/配下で一元管理
- CI/CD: GitHub Actions で Nix ビルド検証と
flake.lockの自動更新を行う。
Directory Structure
dotfiles/
├── conf/ # 設定ファイル（シンボリックリンク対象）
│ ├── .config/ # 標準アプリケーション設定
│ │ ├── nvim/ # Neovim 設定
│ │ ├── nix/ # Nix / Home Manager 設定
│ │ ├── zsh/ # Shell 設定
│ │ ├── git/ # Git 設定
│ │ ├── lazygit/ # Lazygit 設定
│ │ ├── ai-agents/ # AI エージェント共有設定（skills の実体）
│ │ └── ... # その他 30 以上のツール設定
│ ├── .zshrc # Zsh 主設定
│ ├── .claude/ # Claude Code 設定
│ └── .codex/ # Codex 設定
├── scripts/ # セットアップ / リンク作成スクリプト
│ ├── init.sh # 初期セットアップ
│ ├── link.sh # シンボリックリンク作成
│ └── after.sh # インストール後処理
├── .github/workflows/ # GitHub Actions CI/CD
│ ├── build.yaml # Nix ビルド検証
│ └── update.yaml # 自動 flake.lock 更新（3日ごと）
├── flake.nix # Nix flake 設定
├── flake.lock # Nix 依存関係ロック
├── Makefile # 主要操作コマンド
└── README.md # 全体ドキュメント
Common Commands
- セットアップ（macOS）:
make init（初期セットアップ）make link（dotfiles のシンボリックリンク作成）make brew（Homebrew アプリインストール）
- Nix / Home Manager:
make apply-nix（home-manager + nix-darwin を適用）make apply-nix-just-home（Home Manager 設定のみ）make apply-nix-just-darwin（nix-darwin 設定のみ）make update-apply-npm（node-pkgs を更新して home-manager を適用）
- ビルド確認（CI 相当・必要時のみ）:
nix build .#darwinConfigurations.happy-mbp.systemnix build .#homeConfigurations.happy.activationPackage
Nix Guidance
- パッケージ追加は基本的に
conf/.config/nix/home-manager/common.nixを優先。 - OS 固有設定は以下に分離:
- macOS:
conf/.config/nix/home-manager/darwin.nix - Linux:
conf/.config/nix/home-manager/linux.nix
- macOS:
- nix-darwin 固有は
conf/.config/nix/nix-darwin/default.nix。
File Structure
conf/.config/nix/home-manager/common.nix: クロスプラットフォーム共通パッケージconf/.config/nix/home-manager/darwin.nix: macOS 固有設定conf/.config/nix/home-manager/linux.nix: Linux 固有設定conf/.config/nix/nix-darwin/default.nix: nix-darwin 設定
Adding New Packages
conf/.config/nix/home-manager/common.nixのhome.packagesに追加home-manager switch --flake .で適用- コミット（
feat: Add <package-name> to Nix packages）
Neovim Guidance
conf/.config/nvim/lua/plugins/はカテゴリ構造を維持すること。- 新規プラグインは既存カテゴリへ配置し、
lazy.nvim前提で定義すること。 - Lua 変更時は必要に応じて
styluaで整形すること。
Directory Structure
conf/.config/nvim/
├── init.lua # エントリーポイント
├── lazy-lock.json # プラグインバージョンロック
└── lua/
├── core/ # コア設定
│ ├── settings.lua # 基本設定
│ ├── keymaps.lua # キーマップ
│ └── auto-command.lua # 自動コマンド
└── plugins/ # プラグイン設定（17 カテゴリ）
├── ai/ # AI 統合（CodeCompanion, Copilot 等）
├── completion/ # 補完（nvim-cmp, LuaSnip 等）
├── lsp/ # LSP（mason, lspconfig, none-ls 等）
├── edit_support/ # 編集補助（autopairs, surround 等）
├── fuzzyfinder/ # ファジー検索（Telescope）
├── git/ # Git 統合（diffview, octo 等）
├── japanese/ # 日本語対応（kensaku, skkleton 等）
├── navigation/ # ナビゲーション（flash, hop 等）
├── languages/ # 言語別プラグイン（vimtex, metals 等）
├── note/ # ノート機能（orgmode, markdown 等）
├── terminal/ # ターミナル（toggleterm 等）
├── tools/ # ツール統合（which-key, overseer 等）
├── highlight/ # ハイライト（hlchunk 等）
├── treesitter/ # 構文解析（treesitter 等）
├── ui/ # UI 改善（nvim-tree, lualine 等）
├── colorschemas/ # カラースキーム
└── misc/ # その他
Lua Formatting
- pre-commit フックが設定されており、Lua ファイル編集時に自動整形される。
- 設定:
.pre-commit-config.yaml（StyLua v0.20.0）。 - コミット前に自動実行される。
Agent CLI Usage
- Claude Code / Codex は Neovim のターミナルバッファ内で使用している。
conf/.config/nvim/lua/agent_term/にターミナル管理モジュールがある。- 主要コマンド: AgentClaude, AgentCodex, AgentClaudeRestart, AgentClaudeFork など。
- エージェント CLI に関する提案は、tmux 直接ではなく Neovim コマンド経由を優先すること。
Pi Settings Management
~/.pi/agent/settings.jsonは生成物。dotfiles のconf/.pi/agent/settings.base.json（宣言的・コミット対象）と~/.pi/agent/settings.local.json（マシン固有）をscripts/pi-settings.shがマージして生成する。- プラグイン追加・削除など宣言的な変更は
conf/.pi/agent/settings.base.jsonを直接編集し、make pi-pushで反映する。 pi install/pi removeで settings.json を直接書き換えないこと（生成物のため、次回 push で上書きされる）。- 書き換えてしまった場合は
make pi-pullで base.json / local.json へ再構築できる。 - local に振り分けるキーは
conf/.pi/agent/managed-paths.jsonで管理（theme, defaultModel など runtime で変わる設定）。
Development Workflow
Commit Message Convention
- Conventional Commits 準拠:
feat:（新機能追加）fix:（バグ修正）refactor:（リファクタリング）docs:（ドキュメント更新）[bot]:（自動更新系・flake.lock 等）
- 言語: 英語または日本語（混在可）。
Branch Naming Convention
feat-*/feat/*: 新機能fix-*/fix/*: バグ修正refactor-*/refactor/*: リファクタリングupdate/*: 更新auto-updates: 自動更新用（GitHub Actions）
Worktree Usage
- 既存のローカル変更と分離して作業する場合は
git worktreeを使う。 - 標準配置は
../dotfiles-wt/<task-slug>、branch はwt/<task-slug>とする。 - worktree 作成後は、以降の編集・検証を作成先の worktree で行う。
- worktree で作業する際は、変更を区切りよく適宜コミットして進める。
- worktree で PR を作成する前に、必ず
git fetch origin mainを実行し、ローカルmainとorigin/mainに差分がないか確認する。 - ローカル
mainがorigin/mainより古い、または PR ブランチが最新のmainを取り込んでいない場合は、PR 作成前に最新のmainを PR ブランチへ取り込む。
Applying Worktree Changes Locally
- このリポジトリの設定は
conf/から$HOME配下へ symlink されるため、worktree 側の変更を実環境で試すには worktree でmake linkを実行する。 make link実行後は~/.config/nvimなどが worktree のconf/を指す。検証対象の worktree が正しく反映されているかreadlink ~/.config/nvimなどで確認する。make linkは$HOME配下の symlink を張り替える操作なので、どの worktree を実環境へ向けているかを意識する。scripts/link.shはconf/.config/ai-agents/skills/nipposymlink を生成することがある。これは作業本体と無関係な未追跡差分として出る場合がある。
Editing Policy
- 変更は最小・局所的に行い、既存スタイルを維持すること。
- 主な編集対象は
conf/とscripts/。 - 既存のユーザー設定を勝手に整理・統合・削除しないこと。
- 破壊的コマンドを実行しないこと（明示依頼がある場合を除く）。
- 例:
rm -rf,git reset --hard, 強制 checkout
- 例:
- 関係ないローカル変更は revert しないこと。
Validation Policy
- まず変更箇所に近い軽量検証を優先すること。
- 大規模・長時間の検証は、必要性がある場合のみ実行すること。
- 無関係な不具合修正は行わないこと。
Command Safety
rg/find/duなどの再帰検索は、対象ディレクトリを必要最小限に絞ること。~/.npm,~/.local/share,~/.cache,node_modules,.git,miseなどの巨大なキャッシュ・依存ディレクトリ全体を安易に検索しないこと。- ホーム配下や共有データ配下を調査する場合は、まず具体的なファイル・プラグイン・ログディレクトリに限定すること。
- 広めの検索が必要な場合は、
--globによる除外、--max-filesize、-m/--max-countなどで走査量と出力量を制限すること。 2>/dev/nullで stderr を捨てても stdout の大量出力は残るため、CodeCompanion / Codex 上で固まる原因になる。大量出力が予想される場合は、検索対象や件数を先に絞ること。
Secrets and Safety
- トークン/鍵/認証情報を出力・コミットしないこと。
- 例:
~/.codex/auth.jsonなどの機密情報は参照しても内容を露出しないこと。
Response Style
- 端的かつ実務的に報告すること。
- 最終報告には以下を含めること:
- 何を変えたか
- 変更ファイル
- 実行した検証コマンド