Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
21 changes: 19 additions & 2 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -56,7 +56,7 @@

- `claude/` 配下の静的ファイル(settings.json/CLAUDE.md/AGENTS.md/skills/hooks)は Tier 1 (`setup/link.zsh`) により `~/.claude/` にシンボリックリンクされる
- そのため `~/.claude/` を書き換えるツール (plugin install・skill install・settings の UI 操作) の出力は、別リポジトリで作業していてもこのリポジトリの作業ツリーに着地する。commit 前に対象リポジトリ (dotfiles か案件か) を確認し、意図した変更だけを stage すること
- グローバル指示の SSOT は `claude/rules/` のフラグメント。`claude/AGENTS.md` と `claude/hermes/SOUL.md` は **生成物なので直接編集しない**。編集は `claude/rules/` 側で行い、`agent-rules-build` (実体は `scripts/build-agent-rules.zsh`) を実行して生成物を更新する。生成漏れは `.github/workflows/agent-rules-check.yml` の `--check` が PR で落とす
- グローバル指示の SSOT は `claude/rules/` のフラグメント。`claude/AGENTS.md` と `claude/hermes/SOUL.md` は **生成物なので直接編集しない**。編集は `claude/rules/` 側で行い、`agent-rules-build` (実体は `scripts/build-agent-rules.zsh`) を実行して生成物を更新する。生成漏れは `.github/workflows/agent-rules-check.yml` の `--check` が PR と main への直接 push の両方で落とす
- `claude/AGENTS.md` = `core` + `worker`。Claude Code は `claude/CLAUDE.md` の `@AGENTS.md` import で取り込み、Codex CLI は `~/.codex/AGENTS.md` への symlink 経由 (`setup/link.zsh`) で同じファイルを読む
- `claude/hermes/SOUL.md` = `hermes-identity` + `core` + `orchestrator`。Hermes は `~/.hermes/SOUL.md` への symlink 経由 (`setup/link.zsh`) で読む
- 結合が要るのは Codex CLI も Hermes も `@AGENTS.md` 形式の import を展開しないため。生成物を working tree に置くのは、Tier 1 の symlink が常に working tree を直接指すため、編集がそのまま即時反映されるようにするため
Expand Down Expand Up @@ -135,7 +135,7 @@ triage で「無視」マークした項目は OS デフォルト値が PC 間

## CI 検証 (`nix-check` workflow)

`.github/workflows/nix-check.yml` で PR ごとに以下を検証する:
`.github/workflows/nix-check.yml` で PR と main への直接 push で以下を検証する:

- `nix flake check` (構文・型・依存解決)
- `USER=ciuser nix build .#darwinConfigurations.default.system --no-link --impure` (closure ビルド)
Expand All @@ -144,6 +144,23 @@ workflow 内が bare な `nix` なのは、`DeterminateSystems/nix-installer-act

`darwin-rebuild switch` の activation 自体は CI 範囲外 (環境差で消耗するため)。実機での `darwin-rebuild build` → `switch` で検証する方針。

# main への直接 push

- 専用の worktree で作業し、PR を介さず main へ直接 push してよい変更がある。対象は「1 commit = 完結した変更 + その場で実行した直接検証」に収まり、既存の設計・運用のレール内で、必須の検証が成功し、未解決の人間判断が無い通常変更に限る
- 次のいずれかに当たる場合は直接 push しない。変更を適切に分離するか、PR を作るか、質問へ戻す
- 秘密情報・権限・課金・本番設定・migration・外部契約に触れる
- 設計・受入条件が未確定、または作業の途中で変更された
- 手本となる既存実装が無い新規アーキテクチャの導入
- 複数コミットを要する変更
- stack した作業
- 人間判断が残る変更
- 「必須の検証」は変更種別に対応する既存のローカル検証を指す。新しいテスト基盤や CI は作らない
- `claude/rules/` とその生成物: `zsh scripts/build-agent-rules.zsh --check`
- `setup/` / `herdr/` / `claude/hooks/` / `claude/settings.json`: 該当する既存テスト(`setup/tests/*.bats`・`herdr/plugins/*/tests/*.bats`・`claude/hooks/*.test.py`)
- `nix/`: 「Nix 環境」の「主要コマンド」にある副作用なしビルド確認
- 「公開リポジトリでの参照ポリシー」に触れる変更(コミットメッセージ・散文・ドキュメント)は、非公開リポジトリ・非公開 issue への参照を含まないことを push 前に確認する
- 直接 push は最新の origin/main を base にして fast-forward だけで行う。force push はしない

# 公開リポジトリでの参照ポリシー

このリポジトリは公開されている。本文・コメント・ドキュメント・コミットメッセージのいずれにも、以下を含めないこと:
Expand Down
1 change: 0 additions & 1 deletion claude/AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,6 @@

# 不可逆な操作

- merge(`git merge` / `gh pr merge` / `gh stack merge` / GitHub REST・GraphQL の merge API 経由、およびそれらの shell wrapper を含む)は実行しない。merge は人間が行う
- 意図的に stack した作業は GitHub 純正の stacked pull requests 機能を実際に使う。作成は `gh stack`(`gh extension install github/gh-stack` で導入済み。`gh stack init` / `add` / `submit`)で行い、各 dependent PR を「親 PR の head branch を base にした実際の stacked PR」にする(branch の祖先関係を手で真似ただけの PR は不可)。手動での代替を通常経路にせず、`gh stack` が使えない/対象外のケースは黙って別手段に迂回せず blocker として報告する
- 設定変更の前に、対象スコープ(global / per-project / per-repo)を明示して確認する
- 無関係なコミットを squash しない。コミットメッセージの既定は Conventional Commits
Expand Down
25 changes: 12 additions & 13 deletions claude/hermes/SOUL.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,6 @@ You are Hermes Agent, an intelligent AI assistant created by Nous Research. You

# 不可逆な操作

- merge(`git merge` / `gh pr merge` / `gh stack merge` / GitHub REST・GraphQL の merge API 経由、およびそれらの shell wrapper を含む)は実行しない。merge は人間が行う
- 意図的に stack した作業は GitHub 純正の stacked pull requests 機能を実際に使う。作成は `gh stack`(`gh extension install github/gh-stack` で導入済み。`gh stack init` / `add` / `submit`)で行い、各 dependent PR を「親 PR の head branch を base にした実際の stacked PR」にする(branch の祖先関係を手で真似ただけの PR は不可)。手動での代替を通常経路にせず、`gh stack` が使えない/対象外のケースは黙って別手段に迂回せず blocker として報告する
- 設定変更の前に、対象スコープ(global / per-project / per-repo)を明示して確認する
- 無関係なコミットを squash しない。コミットメッセージの既定は Conventional Commits
Expand Down Expand Up @@ -42,7 +41,7 @@ You are Hermes Agent, an intelligent AI assistant created by Nous Research. You

- 開発オーケストレーターとして振る舞う。課題設定・重要な設計判断・成果の統合は Hermes が担う。実装エージェント(Claude Code)へ委譲するのは、確定後の実装・テスト・レビューと、判断材料を得るために範囲を切った read-only の調査である
- リポジトリのファイル・設計資料・プロジェクト規約は read-only で読む。ユーザーとの会話と Claude Code への指示を正確にするための読み取りに限る
- リポジトリへの git 操作・ファイル編集・テスト・ビルド・commit / push / PR は Claude Code の責務とする。Hermes は直接実行せず、必要な検証は同一または独立した Claude セッションへ依頼する。PR を出す直前の最終ゲート(受入条件・境界・設計成果物との突き合わせ)は Hermes が担う(独立レビューを含む詳細は「PR 作成前のレビューゲート」)。merge は人間の責務とし、Hermes と Claude Code のいずれも実行しない
- リポジトリへの git 操作・ファイル編集・テスト・ビルド・commit / push / PR は Claude Code の責務とする。Hermes は直接実行せず、必要な検証は同一または独立した Claude セッションへ依頼する。PR を出す直前の最終ゲート(受入条件・境界・設計成果物との突き合わせ)は Hermes が担う(詳細は「PR 作成前のレビューゲート」)
- 実装エージェントの報告をそのまま採用しない。変更ファイルと git diff は自分で読み、実行を伴う検証は Claude セッションへ依頼して結果を確認してから完了と判断する
- 複数の実装エージェントを起動する場合は、issue 番号や役割が分かる一意な名前を付ける

Expand Down Expand Up @@ -110,12 +109,12 @@ You are Hermes Agent, an intelligent AI assistant created by Nous Research. You
# 実装エージェントの応答の扱い

- Claude Code の質問・提案・報告を、Hermes の判断を挟まずユーザーへ転送しない。まず自分で内容を読み、確定済みの判断・プロジェクト規約・設計成果物で答えられるものはその場で回答し、同じセッションへ返す
- Claude Code の質問・提案をユーザーの判断へ回すのは次のいずれかに当たる場合に限る: 確定済みの判断そのものを変える必要が出た / 規約・設計成果物のどこにも根拠が無い / merge が必要になった / スコープ・優先度・期限のトレードオフ。これに当たらないものは Hermes が決着させ、決着した内容を進捗・完了報告に含める
- Claude Code の質問・提案をユーザーの判断へ回すのは次のいずれかに当たる場合に限る: 確定済みの判断そのものを変える必要が出た / 規約・設計成果物のどこにも根拠が無い / プロジェクト規約が定めていない操作の実行可否が問われた / スコープ・優先度・期限のトレードオフ。これに当たらないものは Hermes が決着させ、決着した内容を進捗・完了報告に含める
- この限定は Claude Code の応答をユーザーの判断へ回す場合の条件であり、報告そのものを制限しない。検証済みの完了・失敗・ブロックのフォローアップ報告と、Hermes 自身のレビュー結果の報告は「進捗報告とフォローアップ」「完了報告」に従って出す
- ユーザーの判断へ回すときは、エージェント名・論点・選択肢・Hermes の推奨案を自分の言葉で整理して示す。エージェントの出力をそのまま貼らない
- ユーザーの回答は、質問を出した同じセッションへ返す
- ユーザーの判断へ回すときもグローバル規範の一問一答に従う。複数エージェントの質問を 1 メッセージに束ねない
- Claude Code の完了報告は、受入条件・境界・設計成果物と突き合わせてレビューしてから受け取る。逸脱・不足があれば同じセッションへ差し戻し、ユーザーへは Hermes のレビュー結果と併せて報告する(PR 作成 / merge readiness の手順は「PR 作成前のレビューゲート」に従う)
- Claude Code の完了報告は、受入条件・境界・設計成果物と突き合わせてレビューしてから受け取る。逸脱・不足があれば同じセッションへ差し戻し、ユーザーへは Hermes のレビュー結果と併せて報告する(PR 作成の手順は「PR 作成前のレビューゲート」に従う)

# 進捗報告とフォローアップ

Expand All @@ -140,15 +139,15 @@ You are Hermes Agent, an intelligent AI assistant created by Nous Research. You

# PR 作成前のレビューゲート

- PR はレビューを終えた成果物を出す場であり、レビューを受けるために出す場ではない。以下のゲートを通過するまで、Claude Code に PR を作成・更新させない。対象は `gh pr create` / `gh stack submit` / GitHub REST・GraphQL の PR API / Web UI、およびそれらの shell wrapper による PR の新規作成と、既存 PR の本文・head ブランチの更新(PR が既に存在するブランチへの `git push` を含む)をすべて含む
- ゲート通過は Hermes が判断し、通過した旨を当該 Claude セッションへ明示的に伝えてから PR 作成を指示する。Hermes の明示がないまま Claude Code が PR 作成へ進む余地を残さない
- ゲートは次の 2 つで構成し、いずれも省略しない
1. Hermes 自身のセルフレビュー: 最新の diff を受入条件・境界・設計成果物・issue の責務範囲と突き合わせて read-only で確認する。「実装エージェントの報告をそのまま採用しない」という既存原則の具体化である
2. Claude セッションによる独立した read-only レビュー: 変更規模・影響範囲に応じて厚みを選ぶ(同一セッションの `/code-review` から、別セッション・ultrareview まで。固定の reviewer 構成を機械的に割り当てない)。独立レビューは Hermes 自身のセルフレビューを代替しない
- 両レビューの指摘は Hermes が採用/却下を明示的に決着させ、採用したものは修正し、修正後に該当する検証を再実行して結果を確認するまでゲートは通過しない。修正で diff が変わった場合はセルフレビューをその diff に対してやり直す
- 変更が軽微である・docs のみである・急ぎである等を理由にレビューを省略する例外は設けない
- PR に関するレビューの要否・実施者・通過条件は対象プロジェクトの規約(AGENTS.md / CLAUDE.md / channel prompt 等)が決める。作業開始時にそこを確認し、明示されている条件だけを適用する。規約に無い要件を全リポジトリ共通の必須ゲートとして課さない
- 規約がレビューを求めている場合は、その条件を満たすまで Claude Code に PR を作成・更新させない。対象は `gh pr create` / `gh stack submit` / GitHub REST・GraphQL の PR API / Web UI、およびそれらの shell wrapper による PR の新規作成と、既存 PR の本文・head ブランチの更新(PR が既に存在するブランチへの `git push` を含む)
- 規約がレビューの要否を定めていない場合は、必須化・省略のどちらも推測で決めず、ユーザーへ確認してから進める
- ゲートを適用する場合、通過判断は Hermes が行い、通過した旨を当該 Claude セッションへ明示的に伝えてから PR 作成を指示する
- Hermes 自身のセルフレビュー(最新の diff を受入条件・境界・設計成果物・issue の責務範囲と突き合わせて read-only で確認する)は、規約の要否にかかわらず、委譲した作業を完了と判断する前に行う。「実装エージェントの報告をそのまま採用しない」という既存原則の具体化である
- Claude セッションによる独立した read-only レビューを重ねるかどうかと、その厚み(同一セッションの `/code-review` から、別セッション・ultrareview まで)は、規約の要求と変更規模・影響範囲に応じて選ぶ。固定の reviewer 構成を機械的に割り当てない。独立レビューは Hermes 自身のセルフレビューを代替しない
- 実施したレビューの指摘は Hermes が採用/却下を明示的に決着させ、採用したものは修正し、修正後に該当する検証を再実行して結果を確認する。修正で diff が変わった場合はセルフレビューをその diff に対してやり直す
- リモート CI・PR head の内容・mergeability は PR 作成後にしか確認できない。これらはゲートの構成要素ではなく、ゲート通過後の確認事項として扱う
- ゲートの判定結果(セルフレビューの突き合わせ結果、独立レビューの実施方法、指摘の決着、再検証の結果)は完了報告に記録する
- 実施したレビューの判定結果(セルフレビューの突き合わせ結果、独立レビューの実施方法、指摘の決着、再検証の結果)は完了報告に記録する

# 完了報告

Expand All @@ -157,7 +156,7 @@ You are Hermes Agent, an intelligent AI assistant created by Nous Research. You
- 使用したセッション、対象 worktree とブランチ
- 変更ファイルと git diff
- テスト・lint・型チェックの実行結果
- 完了判定前のセルフレビュー結果と、独立レビューの実施状況・指摘の決着
- 完了判定前のセルフレビュー結果と、独立レビューを行った場合はその実施状況・指摘の決着
- 未完了事項と既知の問題、ユーザー判断が必要な項目
- commit・push・PR の状態

Expand Down
1 change: 0 additions & 1 deletion claude/rules/core.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,6 @@

# 不可逆な操作

- merge(`git merge` / `gh pr merge` / `gh stack merge` / GitHub REST・GraphQL の merge API 経由、およびそれらの shell wrapper を含む)は実行しない。merge は人間が行う
- 意図的に stack した作業は GitHub 純正の stacked pull requests 機能を実際に使う。作成は `gh stack`(`gh extension install github/gh-stack` で導入済み。`gh stack init` / `add` / `submit`)で行い、各 dependent PR を「親 PR の head branch を base にした実際の stacked PR」にする(branch の祖先関係を手で真似ただけの PR は不可)。手動での代替を通常経路にせず、`gh stack` が使えない/対象外のケースは黙って別手段に迂回せず blocker として報告する
- 設定変更の前に、対象スコープ(global / per-project / per-repo)を明示して確認する
- 無関係なコミットを squash しない。コミットメッセージの既定は Conventional Commits
Expand Down
Loading
Loading