dotfiles

macOS環境の設定ファイルを管理するリポジトリです。シンボリックリンク方式で、実ファイルをこのリポジトリ内に置き、ホームディレクトリからリンクを張ります。

ディレクトリ構造

dotfiles/
├── setup.sh              # セットアップスクリプト（シンボリックリンク作成）
├── macos.sh              # macOS設定の自動適用スクリプト
├── Brewfile              # Homebrewパッケージ一覧
├── zsh/
│   ├── .zshrc            # シェル設定（mise, direnv, PATH）
│   ├── .zprofile         # ログインシェル設定（Homebrew）
│   └── .zshenv           # 全シェル共通の環境変数
├── git/
│   └── .gitconfig        # Gitのグローバル設定
├── mise/
│   └── config.toml       # miseで管理する言語ランタイム・ツール定義
├── gh/
│   └── extensions        # gh拡張機能一覧
├── claude/
│   ├── CLAUDE.md         # グローバル指示
│   ├── settings.json     # 共有permissionsの定義（Claude Code向け設定もここ）
│   ├── skills/           # カスタムスキル
│   ├── hooks/            # 共有フック（ガード本体）
│   ├── agents/           # サブエージェント定義
│   ├── docs/             # エージェント向けドキュメント（テスト実装ルール等）
│   └── rules/            # ファイルパターン別ルール（Claude Code形式）
├── cursor/
│   ├── rules/            # Cursor User Rules（*.mdc）
│   ├── hooks.json        # Cursorフック設定
│   ├── hooks/            # 共有フック呼び出し用アダプター
│   ├── statusline.sh     # CLI statuslineアダプタ
│   ├── cli-permissions.json
│   └── cli-statusline.json
├── codex/
│   ├── README.md         # フック実装の補足（運用は README.md）
│   ├── config.toml       # Codex CLI 設定（model・TUI 等）
│   ├── hooks.json        # Codex フック登録
│   ├── hooks/wrap/       # claude/hooks 呼び出しラッパ
│   ├── rules/            # prefix_rule（npm install 禁止等）
│   └── agents/           # サブエージェント TOML（SUBAGENT.md から生成）
├── scripts/
│   ├── sync-cursor-cli-permissions.sh
│   ├── merge-cursor-cli-config.sh
│   ├── merge-codex-config.sh
│   ├── generate-codex-agents.sh
│   └── generate-codex-agents.py
└── docs/
    └── tools/            # 開発ツールのドキュメント

Macの初期化

調子が悪い場合や、新しいMacへ移行する前の既存Macの整理時に実施します。初期化後は「新しいマシンでのセットアップ」に従います。

参考: Macを消去して出荷時の設定にリセットする - Apple公式

事前準備

PCのデータをバックアップします（Time Machineまたは外付けディスクへコピー）
クラウドで管理できないアプリの設定をエクスポートします
- Raycast — Advanced → ExportでDropboxに設定ファイルをエクスポートします
デバイス台数に上限があるアプリのライセンス認証を解除します。Adobe・Microsoft Officeなどのサブスクリプション製品や、1Passwordなどのセキュリティ系アプリが対象になることがあります。管理者に確認してから進めます

初期化

システム設定 → 一般 → 転送またはリセット → すべてのコンテンツと設定を消去
ウィザードにしたがって進めます。次が自動で処理されます
- Apple IDのサインアウトとアクティベーションロックの解除
- 「Macを探す」の解除
- Bluetoothデバイスのペアリング解除
- Touch IDの指紋情報の削除

新しいマシンでのセットアップ

macOSのセットアップウィザード

macOSのセットアップウィザードにしたがって、Wi-Fiへ接続し、Apple IDでサインインします。

初期設定

1. SafariでNotionにログインする

各種情報を参照するため、最初に開いておきます。

2. HHKBを新しいMacにBluetoothでペアリングする

キーマップやペアリング情報はキーボード本体に保存されるため、新しいMacで必要な作業はペアリングだけです。キー操作の詳細は取扱説明書（PDF）を参照してください。

キーボードの電源スイッチを長押し（1秒以上）して電源を入れます
Fn + Qを押してペアリング待機モードにします
Fn + Control + 数字キー（1〜4）を押して登録先のスロットを指定します。スロット1を自宅用のMac、スロット2以降を案件用のマシンに割り当てます
Mac側のBluetooth設定で「HHKB-Hybrid_n」（nはスロット番号）を選び、表示されたペアリング用の数字を入力します
「キーボードの種類を選択」が出たら「JIS（日本語）」を選びます

次はセットアップ手順では不要ですが、定期的に必要になる操作です（設定はキーボード本体に保存されます）。

接続先の切り替え: Fn + Control + 数字キー（1〜4）で登録済みのスロットを切り替えます
USB Type-C接続への切り替え: Fn + Control + 0で切り替えます。ファームウェア更新時はBluetoothではなくUSB接続が必要なため、先にこの操作をします
ファームウェアの更新: HHKBキーマップ変更ツールのメニュー「ヘルプ → 更新プログラムの確認 → HHKBファームウェア」で最新版が出たら.hfbファイルをダウンロードし、「キーボードファームウェア更新」から適用します

3. 外部ディスプレイとマウスを設定する

Macの詳細設定は後の手順で行うため、ここでは作業しやすくするための最小限の設定にとどめます。

システム設定 → ディスプレイ → 配置で外部モニターを主ディスプレイに設定します
解像度を変更します（27インチ4Kの場合は3008×1692）
マウスを接続し、システム設定 → マウスで速度を最大に設定します

開発環境の構築

4. Command Line Toolsをインストールする

xcode-select --install

5. Claude Codeをインストールする

mise管理下には置かず、公式ネイティブインストーラーで導入します（npm版は非推奨です。自動更新がmiseのshimsと競合するため）。curlだけで入り、Homebrewやmiseに依存しません。先に入れておくと、以降の手順でClaudeに相談しながら進められます。

curl -fsSL https://claude.ai/install.sh | bash

インストーラーは本体バイナリ（約200MB）を進捗表示なしでダウンロードします。実行後しばらく無反応に見えますが、これは正常な挙動なのでCtrl+Cで中断しないでください。回線次第で数分かかります。完了を待つ間は別のターミナルタブでステップ6（Homebrew）以降を進めて構いません。進捗を確認したい場合は、別タブで次のコマンドを繰り返します（サイズが増えていればダウンロード中です）。

ls -l ~/.claude/downloads/

完了すると~/.local/bin/claudeに配置されます。この時点ではPATH優先設定がまだ効かないため、フルパスで動作確認します（旧版が残っている場合のシャドウ回避のため、初回は必ずフルパスで叩きます）。

~/.local/bin/claude --version
~/.local/bin/claude doctor

ステップ7のdotfiles適用後は.zshrc/.zshenvで~/.local/binがmiseのshimsより前に来るため、ネイティブ版が優先されます。ネイティブ版が自動更新を担うため、DISABLE_AUTOUPDATER等は設定しません。

6. Homebrewをインストールする

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

Apple Siliconの場合、インストール完了時にPATHを通すコマンドの案内が表示されます。案内にしたがって次を実行します（.zprofileへの追記はステップ7でdotfilesのシンボリックリンクに置き換わりますが、現在のシェルへ反映するためここで実行します）。

echo >> ~/.zprofile
echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zprofile
eval "$(/opt/homebrew/bin/brew shellenv)"

7. ディレクトリを作成してdotfilesをセットアップする

作業ディレクトリはホーム直下に作ります。MYは個人リポジトリ、PROJECTは案件リポジトリ、Screenshotはスクリーンショットの保存先です。~/Documents配下は避けます（iCloud同期の対象だとコピーが遅くなったり、rebase実行時に不要なファイルが生成されたりするため）。クローンはSSH設定前のためHTTPSを使います。

mkdir -p ~/MY ~/PROJECT ~/Screenshot
git clone https://github.com/manabuyasuda/dotfiles ~/MY/dotfiles
brew bundle install --file=~/MY/dotfiles/Brewfile --verbose

インストールの途中で、アプリ（cask）によってはパスワードを求められる場合があります。brew bundle installが完了すると、次のように表示されます。

Homebrew Bundle complete! XX Brewfile dependencies now installed.

brew bundle installの完了後、続けて次を実行します（setup.shはインストール完了直後に実行できます）。

cd ~/MY/dotfiles && ./setup.sh
mise trust ~/.config/mise/config.toml
mise install node
mise install
mise exec -- npm ci
mise exec -- npx lefthook install

brew bundle installとmise installはどちらも時間がかかります。完了を待つ間、依存関係のないステップ8（SSH鍵）・9（フォント）・11（macOS設定）を並行して進められます。

setup.shは次を実行します。何度実行しても安全です（冪等）。

既存ファイルを~/.dotfiles_backup/にバックアップしてからシンボリックリンクを作成します
gh/extensionsに記載されたgh拡張機能をインストールします
node_modulesがある場合はlefthookのpre-commitフックを配置します（npm ciより前に実行するとスキップされるため、後述のnpx lefthook installで別途配置します）
~/.local/share/bashlex-venvにbashlexを導入したPython venvを作成します。pre-tool-use/verify-package-install.shがコマンド文字列をAST解析してnpm installの誤検知を防ぐために利用します。venvがすでにありbashlexも入っていればスキップし、python3がない環境では作成自体をスキップします（hookはbashフォールバック経路で動作します）
cursor/配下を~/.cursor/にリンクし、CLI permissions / statusLineをマージします（詳細は「AIエージェントの共有設定」のCursor節）。Cursorを使う場合はsetup.sh後にCursorを再起動するかDeveloper → Reload Windowを実行してください。

mise installの各行は次の理由によります。

mise trustは、カレントディレクトリのリポジトリ内にあるmise/config.tomlがローカル設定として検出され、未信頼のままでは読み込めないために実行します。
nodeを先に単体で導入するのは、npm:バックエンドのツール（mermaid-cliなど）がバージョン解決にnpmを必要とするためです。nodeがない状態でmise installを実行するとnpm:*の解決がNo such file or directoryで失敗します。
pnpmはmiseのバックエンドがGitHubのリリースから取得するため、回線によっては取得に数分かかります。無反応に見えても中断せず完走させてください。

Important

このセットアップは~/.npmrcにignore-scripts=trueとmin-release-age=5（サプライチェーン対策）が設定されている前提です。これにより次の2点に注意が必要です。

mise installが公開直後の新版で失敗することがあります。 min-release-age=5は公開から5日未満の版を拒否するため、npm:ツールのlatestがそうした版を解決するとNo matching version found ... with a date before ...（npmのETARGET）で失敗します。バージョンは固定せずlatestのままにし、失敗したときは後述の「mise installがETARGETで失敗する場合」の手順で対応します。
npm ciでprepareスクリプトが走りません。 ignore-scripts=trueによりprepare（lefthook install）が実行されないため、pre-commitフックは自動配置されません。上記コマンド列のmise exec -- npx lefthook installで明示的に配置します（setup.shもnode_modulesがあれば配置します）。詳細は「textlintとpre-commitフック」を参照してください。

`mise install`がETARGETで失敗する場合

mise installが次のように失敗するときは、対象ツールのlatestが公開5日未満で、~/.npmrcのmin-release-age=5に拒否されています。

mise ERROR npm failed
npm error code ETARGET
npm error notarget No matching version found for vercel@54.7.1 with a date before ...

サプライチェーン対策（公開直後の版を避ける）を維持して対応する場合は、公開から5日経過してからmise installを再実行します。その間、当該ツールが無くても他のセットアップは進められます。

急いで導入する必要があり、対象リリースを信頼できると判断できる場合に限り、その実行のときだけmin-release-ageを無効化します（~/.npmrcは書き換えません）。対象ツールを名指しして上書き範囲を最小化します。

NPM_CONFIG_MIN_RELEASE_AGE=0 mise install npm:vercel@latest

複数のツールがまとめて失敗するときは、引数を付けずに実行すると未導入分をまとめて取得します。

NPM_CONFIG_MIN_RELEASE_AGE=0 mise install

8. SSH鍵を設定してGitHubに登録する

GitHubアカウントごとに鍵とホストエイリアスを分けて管理します。個人アカウントはmy、案件・会社アカウントは案件名など任意のプレフィックスをホスト名に付けます。

個人アカウント用の鍵を作成する

鍵を生成し、macOSキーチェーンに登録します（再起動後もパスフレーズ入力が不要になります）。続けて公開鍵をクリップボードにコピーし、開いたページで個人GitHubアカウントに登録します。

ssh-keygen -t ed25519 -f ~/.ssh/my_id_ed25519
ssh-add --apple-use-keychain ~/.ssh/my_id_ed25519
pbcopy < ~/.ssh/my_id_ed25519.pub
open https://github.com/settings/ssh/new

案件・会社アカウント用の鍵を作成する（アカウントごとに繰り返す）

次はテンプレートです。<prefix>を案件名や会社名（acmeなど。ホスト名はacme.github.comになります）に置き換えてから実行します。

ssh-keygen -t ed25519 -f ~/.ssh/<prefix>_id_ed25519
ssh-add --apple-use-keychain ~/.ssh/<prefix>_id_ed25519
pbcopy < ~/.ssh/<prefix>_id_ed25519.pub
open https://github.com/settings/ssh/new

`~/.ssh/config`を作成する

個人アカウント分は固定なので、次のコマンドで作成します。

mkdir -p ~/.ssh && chmod 700 ~/.ssh
cat >> ~/.ssh/config <<'EOF'
# 個人アカウント
Host my.github.com
  HostName github.com
  AddKeysToAgent yes
  UseKeychain yes
  IdentityFile ~/.ssh/my_id_ed25519
  IdentitiesOnly yes
EOF
chmod 600 ~/.ssh/config

案件・会社アカウントを使う場合は、~/.ssh/configに次のブロックをプレフィックスごとに追記します。

# 案件・会社アカウント（アカウントごとに追加する）
Host <prefix>.github.com
  HostName github.com
  AddKeysToAgent yes
  UseKeychain yes
  IdentityFile ~/.ssh/<prefix>_id_ed25519
  IdentitiesOnly yes

IdentitiesOnly yesはSSHエージェントに他の鍵が読み込まれていても、指定した鍵のみを使うようにする設定です。複数アカウントの混線を防ぐために必須です。

接続を確認する

ssh -T git@my.github.com

Hi <個人アカウント名>! You've successfully authenticated...と表示されれば成功です。案件アカウントはssh -T git@<prefix>.github.com（<prefix>は設定したホスト名）で同様に確認します。

dotfilesのリモートURLをSSHに変更して個人リポジトリをクローンする

SSHが使えるようになったので、次を実行します。

git -C ~/MY/dotfiles remote set-url origin git@my.github.com:manabuyasuda/dotfiles.git
git clone git@my.github.com:manabuyasuda/manabuyasuda ~/MY/manabuyasuda
git clone git@my.github.com:manabuyasuda/knowledge-base.git ~/MY/knowledge-base

案件リポジトリをクローンする場合

~/PROJECT/配下のリポジトリでは、~/.gitconfig-workの[user]設定でメールアドレスを上書きします。

cat > ~/.gitconfig-work <<'EOF'
[user]
	email = you@company.example
EOF

<prefix>・<org-or-user>・<repo>を実際の値に置き換えて実行します。

git clone git@<prefix>.github.com:<org-or-user>/<repo>.git ~/PROJECT/<repo>

Homebrew・dotfiles・SSHまでの手動セットアップはここまでです。シェルを読み込み直すとmiseが有効になり、~/.local/binがshimsより前に来るのでwhich claudeはネイティブ版を指します。あとはVS Codeでdotfilesを開き、ステップ5で入れたClaude Codeに「ステップ9以降を進めて」と依頼すれば、残りのセットアップを任せられます。

exec $SHELL -l
which claude
code ~/MY/dotfiles
claude

9. フォントをインストールする

Noto Sans JPはBrewfileからインストール済みです。Source Code Proはコマンドで手動インストールします。

curl -LO https://github.com/adobe-fonts/source-code-pro/archive/release.zip
unzip release.zip
cp -a source-code-pro-release/TTF/* ~/Library/Fonts
rm -rf release.zip source-code-pro-release

アプリの設定

10. 各アプリを設定する（Notionを参照）

brewでインストールしたアプリはFinderから1つずつ起動して設定を進めます。アクセシビリティやファイルアクセスなど、セキュリティに関する許可を求められるため、1つずつ確認しながら進めるとわかりやすくなります。

Macの設定

11. `macos.sh`を実行してシステム設定を一括適用する

~/MY/dotfiles/macos.sh

次は手動で設定します。

一般 → ログイン項目（ログイン時に開く）

BetterTouchTool、CotEditor、DeepL、Dropbox、Google Chrome、MeetingBar、Notion、PopClip、Raycast、Slack、Sourcetree、Visual Studio Code

通知（通知を許可する）

MeetingBar、ターミナル、Slack

コントロールセンター（メニューバー）

Spotlight：メニューバーに表示しません

キーボード → キーボードショートカット

Spotlight：すべてオフ（Raycastを使用するため）
入力ソース（前の入力ソースを選択）：オフ
「次のウィンドウを操作対象にする…」を選択し、ショートカットの表示をクリックしてから設定したいショートカットを入力します

キーボード → 入力ソース → 日本語

入力モード：英字にチェックを入れます
タイプミスを修正：オフ
Windows風のキー操作：オン
数字を全角入力：オフ

キーボード → 入力ソース → ABCを削除する

iCloud → iCloudに保存済み → すべて見る

写真：クリックして「このMacを同期」のチェックを外し、「Macから削除」を選びます

12. Macを再起動する

ひととおりの設定が完了したら再起動します。システム設定の変更が反映され、アプリの許可ダイアログなどが表示されます。

AIエージェントの共有設定

Claude Code・Cursor・Codexで、同じガード・permissions・ルール・スキルを使う構成です。変更手順は下の表と「運用」を参照し、Codexのフック実装の技術補足はcodex/README.mdを参照してください。

claude/に本体を置き、cursor/とcodex/に各ツール向けの形式へ合わせた設定を置きます。Codexのconfig.tomlはcodex/config.tomlで管理し、setup.shが~/.codex/config.tomlへマージします。

全体像

種類	代表例	要点
1. シンボリックリンク	agents（Claude/Cursor）, skills（Codex）	`claude/agents/`→`~/.claude/agents`と`~/.cursor/agents`。`claude/skills`→`~/.agents/skills`（Codex）
1. シンボリックリンク + @参照	docs	`claude/docs/`を`~/.claude/docs`へシンボリックリンクでつなぎます。CursorはRulesの`@.claude/docs/...`で参照します
1. シンボリックリンク	Codex 指示・フック・rules・agents	`CLAUDE.md`→`~/.codex/AGENTS.md`。`codex/hooks.json`・`codex/rules/`・`codex/agents/`を`~/.codex/`へリンク
2. 別ファイル（手動で同期）	フック、ルール、statusLine	本体は`claude/`に置きます。Cursorは`cursor/hooks.json`とアダプター、Codexは`codex/hooks/wrap/`で呼び出します
2. 生成物	Codex サブエージェント TOML	`claude/agents//SUBAGENT.md`から`scripts/generate-codex-agents.sh`で`codex/agents/.toml`を生成します
3. スクリプト同期	permissions, Codex config	`claude/settings.json`の`permissions`（Cursor CLI）。`codex/config.toml`は`merge-codex-config.sh`で反映します

Codex のファイル配置

ホームのパス	dotfiles	内容
`~/.codex/config.toml`	`codex/config.toml`（merge）	モデル・TUI status line 等。`[projects.]`と`[hooks.state.]`はCodexがローカルに追記します
`~/.codex/AGENTS.md`	`claude/CLAUDE.md`（symlink）	グローバル指示
`~/.codex/hooks.json`	`codex/hooks.json`	フック登録
`~/.codex/hooks/wrap/`	`codex/hooks/wrap/`	`claude/hooks/`呼び出しラッパ
`~/.codex/rules/`	`codex/rules/`	`prefix_rule`（npm install 禁止等）
`~/.codex/agents/`	`codex/agents/`	サブエージェント TOML（生成物）
`~/.agents/skills/`	`claude/skills`（symlink）	スキル

~/.codex/config.tomlはシンボリックリンクにしません。setup.shがscripts/merge-codex-config.shでcodex/config.tomlを反映し、既存のフックtrust（[hooks.state.*]）とプロジェクトtrust（[projects.*]）は保持します。

Codex CLIでは次も踏まえます。

setup.shはCodex CLI本体をインストールしません。未導入のマシンではCLIを入れ、codex loginで認証してから./setup.shを実行します。認証情報は~/.codex/配下に保存されます（dotfiles外）。
非managedのcommandフックは、TUIの/hooksでtrustするまで実行されません。trust状態は[hooks.state.*]に保存され、merge時も保持しますが、dotfilesにはコミットしません。codex/hooks.jsonやラッパを変えたあとは再trustが必要です。
スキルは~/.agents/skills（claude/skillsへのsymlink）を読みます。Claude Codeの~/.claude/skillsとはパスが異なります。
サブエージェントTOMLはscripts/generate-codex-agents.shでclaude/agents/*/SUBAGENT.mdから生成します。SUBAGENT.mdだけ直しても~/.codex/agentsへは反映されません。
commit-message-writerはCodexではClaude Codeのtranscript JSONLを読めません（codex/agents/commit-message-writer.tomlに制約を記載しています）。

変更したいとき

変更後はCursorを再起動してください（setup.shは実行時にpermissionsのsync/merge用スクリプトも自動で実行します）。

変更したいもの	編集するファイル	実行するコマンド	注意
共有のpermissions	`claude/settings.json`	`./scripts/sync-cursor-cli-permissions.sh` → `./scripts/merge-cursor-cli-config.sh`	mergeは`cli-config.json`の`permissions`と`statusLine`だけを更新します。承認ダイアログで足したallowはmergeすると消えますので、残す場合は`settings.json`へ移してください
フックのガード本体	`claude/hooks/`	なし	判定ロジックの本体です。Cursor側の登録は`cursor/hooks.json`と`cursor/hooks/adapters/`にあります（`adapters/`はdotfilesでのディレクトリ名です）
フックのCursor側	`cursor/hooks.json`, `cursor/hooks/adapters/`	`bash cursor/tests/<name>-adapter.test.sh`	本体を新設したときは`claude/hooks/`も追加します。未移植のものは`worktree/*`、`log-denial`、`usage-guard`などがあります（詳細は`claude/SECURITY.md`を参照してください）
サブエージェント	`claude/agents/`	なし	`claude/agents/`から`~/.claude/agents`と`~/.cursor/agents`へシンボリックリンクを張ります
エージェント向けドキュメント	`claude/docs/`	なし	`claude/docs/`を`~/.claude/docs`へシンボリックリンクでつなぎます。Cursorは`@.claude/docs/...`で参照します（`~/.cursor/docs`は作りません）
スキル	`claude/skills/`	なし	`~/.claude/skills`と`~/.agents/skills`（Codex）へシンボリックリンクを張ります
Codex サブエージェント	`claude/agents/*/SUBAGENT.md`	`./scripts/generate-codex-agents.sh` → `git add codex/agents/`	生成物は`codex/agents/*.toml`。`setup.sh`で`~/.codex/agents`へリンクします
Codex フック登録	`codex/hooks.json`, `codex/hooks/wrap/`	なし	本体は`claude/hooks/`。SessionStart/PostToolUseはラッパでJSON形式へ変換します。初回および定義変更後はTUIの`/hooks`でtrustが必要です
Codex rules	`codex/rules/`	なし	`~/.codex/rules`へシンボリックリンクを張ります
Codex config.toml	`codex/config.toml`	`./scripts/merge-codex-config.sh`	`[projects.]`と`[hooks.state.]`はローカル状態として保持します。TUIの`/statusline`で変えた`[tui]`は`~/.codex/config.toml`に直接書き込まれるため、dotfilesへ取り込むときは手動コピーします
Codex グローバル指示	`claude/CLAUDE.md`	なし	`~/.codex/AGENTS.md`へシンボリックリンクを張ります
グローバル指示	`claude/CLAUDE.md`	なし	あわせて`cursor/rules/global-instructions.mdc`も更新します（近い内容ですが、同一ではありません）
パス別ルール	`claude/rules/*.md`	なし	あわせて`cursor/rules/*.mdc`も更新します（`paths:`と`globs:`で書式が違います）
Cursor専用ルール	`cursor/rules/*.mdc`	なし	—
statusline	`cursor/statusline.sh`, `cursor/cli-statusline.json`	`./scripts/merge-cursor-cli-config.sh`	Cursor CLIでのみ表示されます（IDE Agentでは表示されません）
Claudeの個別設定を新規追加	`claude/`に作成	`./setup.sh`	`SYMLINKS`への追記が必要な場合は、先に`setup.sh`を編集します
新規マシン・リンクの張り直し	—	`./setup.sh`	実行すると、シンボリックリンクの作成とpermissionsのsync/mergeをまとめて行います

claude/settings.jsonのhooksはClaude Code専用です。Cursorはcursor/hooks.json、Codexはcodex/hooks.jsonを読みます。

StrReplace/DeleteがpreToolUseで発火するかは、Cursorのバージョンに依存します。

運用

設定ファイルを編集した場合

シンボリックリンク経由なので、~/.zshrcなどを直接編集すればリポジトリ内のファイルが更新されます。

cd ~/MY/dotfiles
git diff
git add -A && git commit -m "chore: 変更内容"

Brewfileを更新する場合

brew bundle dump --file=~/MY/dotfiles/Brewfile --force

Claude Codeの設定を追加する場合

claude/ディレクトリ（skills/, hooks/）はディレクトリごとシンボリックリンクされているため、中にファイルを追加すると自動的にリポジトリに反映されます。

keybindings.jsonなど新しい個別ファイルを追加する場合は、claude/に作成してから./setup.shを再実行します。

Claude Code Update Watch

Claude Codeの新バージョンを日次で検知し、このリポジトリの設定への取り込み提案をIssueに投稿するワークフロー（.github/workflows/claude-code-update-watch.yml）です。

実行タイミング: 毎日JST 14:00（UTC 05:00）
仕組み: anthropics/claude-codeのCHANGELOG.mdを取得し、前回処理済みバージョンとの差分をAIが要約してclaude-code-updateラベル付きIssueを作成します
認証: リポジトリSecretのCLAUDE_CODE_OAUTH_TOKEN（claude setup-tokenで発行したOAuthトークン）を使用します

トークンの有効期限と再発行

claude setup-tokenで発行されるトークンの有効期限は1年間です。Maxサブスクリプションが有効である限り使えます。

トークンが失効するとワークフローの「Generate proposal」ステップが認証エラーで失敗します。claude setup-tokenで出力された文字列をコピーし、gh secret setでリポジトリSecretを更新します（「? Paste your secret:」と表示されたら貼り付けます）。

claude setup-token
gh secret set CLAUDE_CODE_OAUTH_TOKEN --repo manabuyasuda/dotfiles

Claude Code対話型ワークフロー（@claude）

IssueやPRで @claude とメンションすると、Claude Codeが文脈を分析してコメント返信・コード実装・PR作成をするワークフロー（.github/workflows/claude.yml）です。

起動条件: Issue本文・タイトル、Issueコメント、PRレビュー、PRレビューコメントに @claude を含む場合
認証: watchワークフローと同じリポジトリSecretの CLAUDE_CODE_OAUTH_TOKEN を使用します（トークンの再発行手順は上記「Claude Code Update Watch」と共通です）
モデル: claude-opus-4-8
想定する使い方: watchワークフローが作る claude-code-update ラベル付きの取り込み提案Issueに対し、@claude この提案を実装して のように指示してPRを作らせます

textlintとpre-commitフック

.mdファイルの文章品質はtextlintで検証します。検知は3層で行います。

ローカルのgit commit時（lefthookによるpre-commit）
CI（.github/workflows/textlint.yml、PR時）
Claude Codeの編集時（PostToolUseフックで実行されるformat.sh）

初回セットアップ

通常はnpm ciまたはnpm install時にpackage.jsonのprepareスクリプトがlefthook installを呼び、.git/hooks/pre-commitが配置されます。ただし~/.npmrcにignore-scripts=trueがある環境ではprepareが走らないため、npx lefthook installを実行して配置します（setup.shもnode_modulesがあれば配置します）。

コミット時の挙動

ステージ済みの.mdファイルに違反があると、コミットがexit code 1で止まります
違反がない場合、通常どおりコミットが完了します
lefthook.ymlのglob: "*.md"（basename match）で対象を絞っているため、.md以外のファイルだけをコミットするときtextlintは走りません

緊急回避

CIや別レビューで品質を担保できる、あるいは違反検知に明らかな誤りがある場合に限り、--no-verifyでフックをスキップできます。

git commit --no-verify -m "..."

CIのtextlintジョブは依然として走るため、--no-verifyでローカルをすり抜けてもPRで再検知されます。常用しないでください。

違反を自動修正したい場合

npm run lint:fix

修正できない違反（半角カナの混入など）は手動で直します。

管理対象外のツール

次はdotfilesでは管理していません。新しいマシンでは手動インストールが必要です。

HHKB — キーマップ変更ツールを手動インストールします。設定はステップ2を参照してください
OpenVPN Connect — 公式サイトからインストールします。設定はNotionを参照してください
Automator（FFmpeg/ImageMagick連携）— 設定手順を参照してください。FFmpegとImageMagickはBrewfileからインストール済みです
VS Code拡張機能 — GitHubアカウント同期で管理します

注意事項

.zprofileのHomebrewパス（/opt/homebrew）はApple Silicon専用です。Intel Macでは異なります
.gitconfigが参照する.gitignore_global、.stCommitMsg、.gitconfig-workは、いずれもdotfilesでは管理していません

Name		Name	Last commit message	Last commit date
Latest commit History 329 Commits
.github		.github
.vscode		.vscode
claude		claude
codex		codex
cursor		cursor
dict		dict
docs/tools		docs/tools
gh		gh
git		git
mise		mise
plan		plan
scripts		scripts
zsh		zsh
.gitignore		.gitignore
.textlintignore		.textlintignore
.textlintrc		.textlintrc
Brewfile		Brewfile
README.md		README.md
lefthook.yml		lefthook.yml
macos.sh		macos.sh
package-lock.json		package-lock.json
package.json		package.json
setup.sh		setup.sh
skills-lock.json		skills-lock.json

Folders and files

Latest commit

History

Repository files navigation