From 9b90974310bc11a17e38669135727fef47e0d353 Mon Sep 17 00:00:00 2001 From: yktsnet Date: Tue, 29 Sep 2026 21:19:21 +0900 Subject: [PATCH] =?UTF-8?q?docs:=20README=20=E3=82=92=20repo-readme=20?= =?UTF-8?q?=E3=81=AE=E5=9E=8B=E3=81=AB=E5=90=88=E3=82=8F=E3=81=9B=E3=80=81?= =?UTF-8?q?=E3=81=A7=E3=81=82=E3=82=8B=E8=AA=BF=E3=81=AB=E6=8F=83=E3=81=88?= =?UTF-8?q?=E3=82=8B?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 地の文をである調に揃える - H1 直下のコアメッセージを「本リポジトリは」で始め、何を実証するかと手段を1文に入れる - Tech Stack 節を Reason 列つきで足す - 役割の分離に、ローカルとリモートの境界と abort の分岐を示す図を足す - 動かす手順を載せない理由を What Is Not Here に書く --- README.en.md | 37 +++++++++++++++++++++++++--- README.md | 69 +++++++++++++++++++++++++++++++++++++--------------- 2 files changed, 84 insertions(+), 22 deletions(-) diff --git a/README.en.md b/README.en.md index 5b146ea..ec8929c 100644 --- a/README.en.md +++ b/README.en.md @@ -4,7 +4,7 @@ [![CI](https://github.com/yktsnet/dotfiles-public/actions/workflows/ci.yml/badge.svg)](https://github.com/yktsnet/dotfiles-public/actions/workflows/ci.yml) -A personal development environment for handing development to AI agents, published as a Nix configuration together with the rules it enforces. +This repository is a personal development environment for handing development to AI agents, published with its full configuration as a working example of placing the rules to be followed in the environment (Nix, Claude Code deny rules and hooks, skills) rather than in documents. The parts that carry over to team repositories are packaged separately in [sdlc-kit](https://github.com/yktsnet/sdlc-kit); this is the environment where those practices actually run. --- @@ -52,7 +52,23 @@ When the same model both decides and builds, it cannot notice on its own that it - **Executor**: takes an Issue and carries it through implementation, tests, and a local commit. Never touches the remote ([pr-workflow](.claude/skills/pr-workflow/SKILL.md)) - **User**: approves the Issue's guarantee section, reviews the commits, and publishes them -Hand-offs go through zsh functions. `issue` creates a worktree and launches the executor, `issue-finish` takes a reviewed branch from push through PR, merge, and cleanup, and `issue-abort` discards the worktree along with its branch. Each worktree is isolated, so several Issues can run in parallel. The executor's changes are reviewed line by line in [crit](https://github.com/tomasz-tomczyk/crit). +```mermaid +flowchart TD + U([User]) -->|approve| I[Issue in issues/] + C([Consultant]) -->|design| I + subgraph local [Local worktree] + I -->|issue| E([Executor]) + E --> L[Local commit] + end + L -->|review in crit| R{{User decides}} + R -->|issue-abort| X[Discard with branch] + subgraph remote [GitHub] + P[PR and merge] + end + R -->|issue-finish| P +``` + +The executor stops at a local commit, and the only way out to the remote is the user's `issue-finish`. `issue` creates a worktree and launches the executor, so several Issues can run in parallel. The executor's changes are reviewed line by line in [crit](https://github.com/tomasz-tomczyk/crit). [session-nudge](.claude/skills/session-nudge/SKILL.md) provides a reader standing outside the parallel sessions; it sends advice to another session only after the user approves the draft. Real-time work such as incident response, one-off exceptions the user declares, and small changes that do not touch logic go through without an Issue. @@ -64,6 +80,21 @@ If the mapping existed on only one machine, writing on any other machine would m --- +## Tech Stack + +| Layer | Technology | Reason | +|---|---|---| +| Configuration | Nix Flakes, home-manager | Builds every machine's tools and settings from one declaration, so agents do not stall on machine differences | +| macOS | nix-darwin | Lets macOS share the home-manager layer with the Linux machine | +| Disk | disko | Puts the partition layout in the declaration too, so rebuilding the primary machine does not depend on a runbook | +| Secrets | sops-nix, age | Ships ciphertext through git and lets each machine decrypt with its own key; plaintext never travels between machines | +| Agent | Claude Code | Its `settings.json` deny rules and PreToolUse hooks let prohibitions live as mechanisms rather than documents | +| Review | crit | Comments line by line on the executor's diff or a local page and gets it fixed in place | +| Hand-off | zsh | Turns each role boundary, from creating a worktree to publishing, into one command | +| Sessions | tmux, tmux-claude-session-manager | Moves between parallel Claude Code sessions | + +--- + ## What Ships to sdlc-kit Of the practices running here, the ones that carry over to team repositories are packaged in [sdlc-kit](https://github.com/yktsnet/sdlc-kit). Only practices that meet at least one of three conditions go in: they keep a human decision from being skipped, they have to survive across sessions, or they have to come out the same when the person changes. That covers the task flows, PLAN.md / JUDGE.md for the launch phase, the guarantee ledger after release, and the guards that protect main. The idea of running development on two driving documents is in sdlc-kit's [docs/lifecycle.md](https://github.com/yktsnet/sdlc-kit/blob/main/docs/lifecycle.md). @@ -76,7 +107,7 @@ Unifying tools through Nix, distributing `~/.claude`, decrypting the mapping, an Only the layers involved in developing with agents (Claude Code, memory, secrets, review, and tmux session management) are extracted from the working dotfiles. Editor and desktop settings and server configurations are not included. This is an extract, not a mirror, so some things in the working environment are absent here. The criteria for what gets published are in [.claude/skills/README.md](.claude/skills/README.md). -The repository is not meant to be cloned and applied to your own machines. The device configurations assume the actual hardware and keys, and the encrypted contents of `secrets/` are not included. CI's `nix flake check` confirms that the published configuration still evaluates. +The repository is not meant to be cloned and applied to your own machines, so no setup steps are given. The device configurations assume the actual hardware and keys, and the encrypted contents of `secrets/` are not included. CI's `nix flake check` confirms that the published configuration still evaluates. --- diff --git a/README.md b/README.md index 9377678..05f8403 100644 --- a/README.md +++ b/README.md @@ -4,8 +4,8 @@ [![CI](https://github.com/yktsnet/dotfiles-public/actions/workflows/ci.yml/badge.svg)](https://github.com/yktsnet/dotfiles-public/actions/workflows/ci.yml) -AI エージェントに開発を任せる個人の開発環境を、守らせたい規則ごと Nix 構成として公開したものです。 -チームのリポジトリへ持ち込める分は [sdlc-kit](https://github.com/yktsnet/sdlc-kit) に切り出していて、ここはその型を実際に回している環境にあたります。 +本リポジトリは、AI エージェントに開発を任せる個人の開発環境で、守らせたい規則を文書ではなく環境（Nix・Claude Code の deny とフック・skill）に置く形を、構成ごと公開する実例である。 +チームのリポジトリへ持ち込める分は [sdlc-kit](https://github.com/yktsnet/sdlc-kit) に切り出しており、ここはその型を実際に回している環境にあたる。 --- @@ -19,64 +19,95 @@ AI エージェントに開発を任せる個人の開発環境を、守らせ ## Rules Live in the Environment -規則は置き場で分けています。毎回守らせる規則は CLAUDE.md、「〜するとき」と条件を言える手順と基準は skill、外れてはいけないものは `settings.json` の deny とフックに置きます。そのうえで、どのリポジトリ、どの端末で開いても同じものが効くように、全部を Nix で配ります。 +規則は置き場で分けている。毎回守らせる規則は CLAUDE.md、「〜するとき」と条件を言える手順と基準は skill、外れてはいけないものは `settings.json` の deny とフックに置く。そのうえで、どのリポジトリ、どの端末で開いても同じものが効くよう、全部を Nix で配る。 ### One Toolchain on Every Machine -macOS と Linux の開発機を1つの Flake で管理しています。端末ごとに道具の有無や版が違うと、エージェントは「コマンドが無い」「動きが違う」で止まり、止まった理由の調査に人の時間を取られます。 +macOS と Linux の開発機を1つの Flake で管理する。端末ごとに道具の有無や版が違うと、エージェントは「コマンドが無い」「動きが違う」で止まり、止まった理由の調査に人の時間が取られる。 | 構成 | OS | 役割 | |---|---|---| | `linux-desktop` | NixOS（disko / SSD） | 主開発機。相談者チャットと `issue` の起動元 | | `macbook` | macOS（nix-darwin） | home-manager 層を Linux 機と共有する | -OS の差は、Nix 側では `pkgs.stdenv.isDarwin`、シェル側では `os.sh` のシム（`_is_darwin` / `_sed_i` / `_open` / `_linux_only`）に閉じ込め、それ以外は両 OS が同じファイルを読みます。エージェントが `brew` や `npm -g` に手を伸ばすと `block-non-nix-install.sh` が止め、Nix で入れる手順（[nix-tool-install](.claude/skills/nix-tool-install/SKILL.md)）へ案内します。 +OS の差は、Nix 側では `pkgs.stdenv.isDarwin`、シェル側では `os.sh` のシム（`_is_darwin` / `_sed_i` / `_open` / `_linux_only`）に閉じ込め、それ以外は両 OS が同じファイルを読む。エージェントが `brew` や `npm -g` に手を伸ばすと `block-non-nix-install.sh` が止め、Nix で入れる手順（[nix-tool-install](.claude/skills/nix-tool-install/SKILL.md)）へ案内する。 ### Blocks Are Mechanisms, Not Requests -`rebuild` 系・`flake.lock` の編集・`ssh`・機密の対応表の読み書きは deny で塞いでいます。deny は文字列の前方一致しか見ないので、`/tmp/venv/bin/pip install` のようなパス付きの実行や、`~/.claude` を `sed -i` で書き換えるような、行為として判定が要るものは [PreToolUse フック](.claude/hooks/)で扱います。 +`rebuild` 系・`flake.lock` の編集・`ssh`・機密の対応表の読み書きは deny で塞ぐ。deny は文字列の前方一致しか見ないので、`/tmp/venv/bin/pip install` のようなパス付きの実行や、`~/.claude` を `sed -i` で書き換えるような、行為として判定が要るものは [PreToolUse フック](.claude/hooks/)が受け持つ。 -フックの拒否文には、止めた理由と正しい経路を両方書きます。エージェントは拒否されると別の手を試すので、拒否文に書いた経路へそのまま進みます。編集直後に1ファイルだけ構文検査する `static-check.sh` も同じ考えで、忘れても誰も気づかない確認を、モデルの裁量から外しています。 +フックの拒否文には、止めた理由と正しい経路を両方書く。エージェントは拒否されると別の手を試し、何を試すかは拒否文で決まるので、書いた経路へそのまま進む。編集直後に1ファイルだけ構文検査する `static-check.sh` も同じ考えで作った。忘れても誰も気づかない確認を、モデルの裁量から外している。 ### One Source for Every Session -`.claude/` の settings・hooks・skills と `home-manager/config/claude/common.md` が正本で、`home-manager/modules/claude.nix` が rebuild のたびに `~/.claude` へ実体コピーします。`~/.claude` 側は生成物になるので、そこを直接編集しようとすると `block-live-claude-config-edit.sh` が止め、正本のパスを返します。 +`.claude/` の settings・hooks・skills と `home-manager/config/claude/common.md` が正本で、`home-manager/modules/claude.nix` が rebuild のたびに `~/.claude` へ実体コピーする。`~/.claude` 側は生成物になるので、そこを直接編集しようとすると `block-live-claude-config-edit.sh` が止め、正本のパスを返す。 -規則が増えると、規則同士が食い違い始めます。[consolidate-rules](.claude/skills/consolidate-rules/SKILL.md) が前回の棚卸し地点（`.claude/RULES.md` のアンカー1行）からの差分だけを監査します。永続メモリは `~/memory/` 直下に1ファイル1事実で置き、`memory.nix` で git の経路に乗せて端末間で揃えます。 +規則が増えると、規則同士が食い違い始める。[consolidate-rules](.claude/skills/consolidate-rules/SKILL.md) が、前回の棚卸し地点（`.claude/RULES.md` のアンカー1行）からの差分だけを監査する。永続メモリは `~/memory/` 直下に1ファイル1事実で置き、`memory.nix` で git の経路に乗せて端末間で揃える。 ### Deciding and Building Are Separate -同じモデルが決めて作ると、方向を外したことに自分では気づけません。役割を3つに分けています。 +同じモデルが決めて作ると、方向を外したことに自分では気づけない。そのため役割を3つに分ける。 - **相談者**: user と対話して仕様と Issue を設計する。実装はしない（[new-issue](.claude/skills/new-issue/SKILL.md)） - **実行者**: Issue を入力に、実装・テスト・ローカルコミットまでを進める。リモートには触れない（[pr-workflow](.claude/skills/pr-workflow/SKILL.md)） - **user**: Issue の保証節を裁可し、コミットをレビューして公開する -受け渡しは zsh の関数で行います。`issue` が worktree を切って実行者を起動し、`issue-finish` がレビュー済みのブランチを push から PR・マージ・後片付けまで進め、`issue-abort` は worktree をブランチごと捨てます。worktree ごとに隔離されるので、複数の Issue を並行して走らせられます。実行者の変更は [crit](https://github.com/tomasz-tomczyk/crit) で行単位にレビューします。 - -並行するセッションの外に立つ読み手として [session-nudge](.claude/skills/session-nudge/SKILL.md) があり、別セッションへの助言を、文案を user が承認してから送ります。障害対応のような即時の作業、user が明示した単発の例外、ロジックに触れない小さな変更は、Issue を立てずに通します。 +```mermaid +flowchart TD + U([user]) -->|裁可| I[issues/ の Issue] + C([相談者]) -->|設計| I + subgraph local [ローカルの worktree] + I -->|issue| E([実行者]) + E --> L[ローカルコミット] + end + L -->|crit でレビュー| R{{user の判断}} + R -->|issue-abort| X[ブランチごと破棄] + subgraph remote [GitHub] + P[PR・マージ] + end + R -->|issue-finish| P +``` + +実行者はローカルコミットで止まり、リモートへ出る経路は user の `issue-finish` しかない。`issue` は worktree を切って実行者を起動するので、複数の Issue を並行して走らせられる。実行者の変更は [crit](https://github.com/tomasz-tomczyk/crit) で行単位にレビューする。 + +並行するセッションの外に立つ読み手として [session-nudge](.claude/skills/session-nudge/SKILL.md) があり、別セッションへの助言は、文案を user が承認してから送る。障害対応のような即時の作業、user が明示した単発の例外、ロジックに触れない小さな変更は、Issue を立てずに通す。 ### Secrets Stay Out of the Prose -Issue・PR・コミットの地の文には、IP・ポート・実ホスト名を書かずに `` を使います。実値とプレースホルダの対応表は `secrets-agents/` に置き、エージェントからは読み書きさせません。 +Issue・PR・コミットの地の文には、IP・ポート・実ホスト名を書かずに `` を使う。実値とプレースホルダの対応表は `secrets-agents/` に置き、エージェントからは読み書きさせない。 + +対応表が1台にしか無いと、別の端末では何を伏せるべきか分からないまま書くことになる。対応表は sops（age）で暗号化して git で配り、各端末が自分の鍵で復号する（[sops-secrets](.claude/skills/sops-secrets/SKILL.md)）。 + +--- + +## Tech Stack -対応表が1台にしか無いと、別の端末では何を伏せるべきか分からないまま書くことになります。対応表は sops（age）で暗号化して git で配り、各端末が自分の鍵で復号します（[sops-secrets](.claude/skills/sops-secrets/SKILL.md)）。 +| Layer | Technology | Reason | +|---|---|---| +| 構成管理 | Nix Flakes・home-manager | 全端末の道具と設定を1つの宣言から作れる。エージェントが端末差で止まらない | +| macOS | nix-darwin | macOS でも home-manager 層を Linux 機と共有できる | +| ディスク | disko | パーティション構成も宣言に含め、主開発機の作り直しを手順書に頼らない | +| 機密 | sops-nix・age | 暗号文のまま git で配り、各端末が自分の鍵で復号できる。平文を端末間で運ばない | +| エージェント | Claude Code | `settings.json` の deny と PreToolUse フックで、禁止を文書ではなく機構として置ける | +| レビュー | crit | 実行者の差分やローカルのページに行単位でコメントし、そのまま直させられる | +| 受け渡し | zsh | worktree の作成から公開までを、役割の境目ごとに1コマンドにできる | +| セッション | tmux・tmux-claude-session-manager | 並行する Claude Code のセッションを渡り歩ける | --- ## What Ships to sdlc-kit -ここで回している型のうち、チームのリポジトリへ持ち込めるものを [sdlc-kit](https://github.com/yktsnet/sdlc-kit) に切り出しています。持ち込むのは、人の判断を省かせない、セッションを超えて残す、担当者が替わっても揃う、のどれかに当たるものだけです。作業フロー、立ち上げ期の PLAN.md / JUDGE.md、リリース後の保証台帳、main を守るガードがこれにあたります。開発を2つの駆動文書で回す考え方は sdlc-kit の [docs/lifecycle.md](https://github.com/yktsnet/sdlc-kit/blob/main/docs/lifecycle.md) にあります。 +ここで回している型のうち、チームのリポジトリへ持ち込めるものを [sdlc-kit](https://github.com/yktsnet/sdlc-kit) に切り出している。持ち込むのは、人の判断を省かせない、セッションを超えて残す、担当者が替わっても揃う、のどれかに当たるものだけで、作業フロー、立ち上げ期の PLAN.md / JUDGE.md、リリース後の保証台帳、main を守るガードがこれにあたる。開発を2つの駆動文書で回す考え方は sdlc-kit の [docs/lifecycle.md](https://github.com/yktsnet/sdlc-kit/blob/main/docs/lifecycle.md) にある。 -Nix による道具の統一、`~/.claude` の配布、対応表の復号、永続メモリは端末に紐づくので、チームのリポジトリからは効かせられません。これらはこのリポジトリに残ります。 +Nix による道具の統一、`~/.claude` の配布、対応表の復号、永続メモリは端末に紐づくので、チームのリポジトリからは効かせられない。これらはこのリポジトリに残る。 --- ## What Is Not Here -稼働中の dotfiles から、エージェントとの開発に関わる層（Claude Code・メモリ・機密・レビュー・tmux のセッション管理）だけを抜き出しています。エディタやデスクトップの設定、サーバー類の構成は含めていません。抜き出しであって写しではないので、稼働側にあってここに無いものがあります。何を公開するかの基準は [.claude/skills/README.md](.claude/skills/README.md) にあります。 +稼働中の dotfiles から、エージェントとの開発に関わる層（Claude Code・メモリ・機密・レビュー・tmux のセッション管理）だけを抜き出している。エディタやデスクトップの設定、サーバー類の構成は含めていない。抜き出しであって写しではないので、稼働側にあってここに無いものがある。何を公開するかの基準は [.claude/skills/README.md](.claude/skills/README.md) に置いた。 -clone して各自の端末へ適用することは想定していません。デバイス構成は実機のハードウェアと鍵を前提にしていて、`secrets/` の暗号文も含めていません。CI の `nix flake check` は、公開している構成が評価できる状態にあることを確かめています。 +clone して各自の端末へ適用することは想定しておらず、動かす手順も載せていない。デバイス構成は実機のハードウェアと鍵を前提にしていて、`secrets/` の暗号文も含めていないためである。CI の `nix flake check` は、公開している構成が評価できる状態にあることを確かめている。 ---