From f37e482419c77799af181a297ff58fa626c0337c Mon Sep 17 00:00:00 2001 From: yktsnet Date: Tue, 29 Sep 2026 21:28:23 +0900 Subject: [PATCH] =?UTF-8?q?docs:=20README=20=E3=81=AE=E8=83=8C=E6=99=AF?= =?UTF-8?q?=E3=81=AE=E7=AF=80=E3=82=92=20portfolio=20=E3=81=AE=20Principle?= =?UTF-8?q?s=20=E3=81=AB=E5=9F=BA=E3=81=A5=E3=81=84=E3=81=A6=E6=9B=B8?= =?UTF-8?q?=E3=81=8D=E7=9B=B4=E3=81=97=E3=80=81H3=20=E3=82=92=E6=97=A5?= =?UTF-8?q?=E6=9C=AC=E8=AA=9E=E3=81=AB=E3=81=99=E3=82=8B?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - From Writing to Checking を Verification over Generation に改め、portfolio の「生成より、検証」の主張から書き直す - 根拠の無い体験談と推測の理由（端末差で人の時間が取られる・disko と crit の選定理由）を、確かな記述に差し替える - 日本語版の H3 を日本語にし、Repository Map の対応先を合わせる --- README.en.md | 12 ++++++------ README.md | 34 +++++++++++++++++----------------- 2 files changed, 23 insertions(+), 23 deletions(-) diff --git a/README.en.md b/README.en.md index ec8929c..b2d529a 100644 --- a/README.en.md +++ b/README.en.md @@ -9,11 +9,11 @@ The parts that carry over to team repositories are packaged separately in [sdlc- --- -## From Writing to Checking +## Verification over Generation -As agents wrote more of the code, my own work moved from writing to checking. The more there was to check, the more the way I checked drifted from day to day. On tired days I missed things; on rushed days I skipped steps. The agents were no different: a rule followed in one session got overlooked in the next. +Now that AI writes the code, the time goes not into writing but into confirming that what was written can be trusted. Agents are confidently and quietly wrong, and left alone they carry destructive operations and secret leaks straight into production. A promise that people will be careful eventually becomes an empty formality. -So, bit by bit, I moved what I wanted followed out of documents that ask for compliance and into an environment that leaves no way around it. Neither the people nor the agents are expected to remember. +So removing environment differences, blocking destructive commands, and isolating secrets are fixed in code and configuration, with a human merge as the final gate. Only "what must not break" is decided by a human and approved in writing; implementation and tests are left to the agents. When a promise is broken, a machine detects it and stops, so nobody has to sit and watch. --- @@ -23,7 +23,7 @@ Rules are sorted by where they live. Rules that apply every time go in CLAUDE.md ### One Toolchain on Every Machine -One flake manages the macOS and Linux development machines. When tools or versions differ between machines, agents stall on "command not found" or "behaves differently", and a person ends up spending time finding out why. +One flake manages the macOS and Linux development machines. When tools or versions differ between machines, agents stall on commands that are not found or fail at runtime. | Configuration | OS | Role | |---|---|---| @@ -86,10 +86,10 @@ If the mapping existed on only one machine, writing on any other machine would m |---|---|---| | 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 | +| Disk | disko | Brings even the partition layout into the Nix declaration | | 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 | +| Review | crit | Gives the user and the agent one shared entry point for reviewing the executor's diff and local pages | | 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 | diff --git a/README.md b/README.md index 05f8403..72e10fa 100644 --- a/README.md +++ b/README.md @@ -9,11 +9,11 @@ --- -## From Writing to Checking +## Verification over Generation -エージェントに書かせる量が増えるにつれて、自分の仕事は書くことから確かめることへ移っていった。確かめるものが増えると、確かめ方が日によって揺れる。疲れた日は見落とし、急ぐ日は手順を飛ばす。エージェントも同じで、前のセッションで守れた規則を次のセッションでは読み落とす。 +AI がコードを書くようになって、時間がかかるのは書くことではなく、書かれたものを信じられるか確かめることに変わった。エージェントは自信を持ったまま静かに間違え、放っておけば破壊的な操作や機密の漏洩をそのまま本番へ通す。人が気をつけるという約束は、いずれ形骸化する。 -そこで、守らせたいことを、頼んで守ってもらう文書から、外れようのない環境の側へ少しずつ移してきた。人にもエージェントにも、覚えていることを求めない。 +そのため、環境差の排除・破壊的なコマンドの遮断・機密の隔離はコードと設定で固定し、人間のマージを最後の関門に置いた。「何が壊れてはいけないか」だけは人間が決めて文書で承認し、実装とテストはエージェントに任せる。約束が破られれば機械が検知して止まるので、張り付いて見張らずに済む。 --- @@ -21,9 +21,9 @@ 規則は置き場で分けている。毎回守らせる規則は CLAUDE.md、「〜するとき」と条件を言える手順と基準は skill、外れてはいけないものは `settings.json` の deny とフックに置く。そのうえで、どのリポジトリ、どの端末で開いても同じものが効くよう、全部を Nix で配る。 -### One Toolchain on Every Machine +### 全端末で道具を揃える -macOS と Linux の開発機を1つの Flake で管理する。端末ごとに道具の有無や版が違うと、エージェントは「コマンドが無い」「動きが違う」で止まり、止まった理由の調査に人の時間が取られる。 +macOS と Linux の開発機を1つの Flake で管理する。端末ごとに道具の有無や版が違うと、エージェントはコマンドが見つからない、実行時に失敗する、といった形で止まる。 | 構成 | OS | 役割 | |---|---|---| @@ -32,19 +32,19 @@ macOS と Linux の開発機を1つの Flake で管理する。端末ごとに 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/)が受け持つ。 フックの拒否文には、止めた理由と正しい経路を両方書く。エージェントは拒否されると別の手を試し、何を試すかは拒否文で決まるので、書いた経路へそのまま進む。編集直後に1ファイルだけ構文検査する `static-check.sh` も同じ考えで作った。忘れても誰も気づかない確認を、モデルの裁量から外している。 -### One Source for Every Session +### 規則を1か所から全セッションへ配る `.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 の経路に乗せて端末間で揃える。 -### Deciding and Building Are Separate +### 決める役と作る役を分ける 同じモデルが決めて作ると、方向を外したことに自分では気づけない。そのため役割を3つに分ける。 @@ -72,7 +72,7 @@ flowchart TD 並行するセッションの外に立つ読み手として [session-nudge](.claude/skills/session-nudge/SKILL.md) があり、別セッションへの助言は、文案を user が承認してから送る。障害対応のような即時の作業、user が明示した単発の例外、ロジックに触れない小さな変更は、Issue を立てずに通す。 -### Secrets Stay Out of the Prose +### 機密を地の文に出さない Issue・PR・コミットの地の文には、IP・ポート・実ホスト名を書かずに `` を使う。実値とプレースホルダの対応表は `secrets-agents/` に置き、エージェントからは読み書きさせない。 @@ -86,10 +86,10 @@ Issue・PR・コミットの地の文には、IP・ポート・実ホスト名 |---|---|---| | 構成管理 | Nix Flakes・home-manager | 全端末の道具と設定を1つの宣言から作れる。エージェントが端末差で止まらない | | macOS | nix-darwin | macOS でも home-manager 層を Linux 機と共有できる | -| ディスク | disko | パーティション構成も宣言に含め、主開発機の作り直しを手順書に頼らない | +| ディスク | disko | パーティション構成まで Nix の宣言に含められる | | 機密 | sops-nix・age | 暗号文のまま git で配り、各端末が自分の鍵で復号できる。平文を端末間で運ばない | | エージェント | Claude Code | `settings.json` の deny と PreToolUse フックで、禁止を文書ではなく機構として置ける | -| レビュー | crit | 実行者の差分やローカルのページに行単位でコメントし、そのまま直させられる | +| レビュー | crit | 実行者の差分とローカルのページを、user とエージェントが同じ入口からレビューできる | | 受け渡し | zsh | worktree の作成から公開までを、役割の境目ごとに1コマンドにできる | | セッション | tmux・tmux-claude-session-manager | 並行する Claude Code のセッションを渡り歩ける | @@ -115,9 +115,9 @@ clone して各自の端末へ適用することは想定しておらず、動 | パス | 中身 | 対応する節 | |---|---|---| -| `flake.nix`・`devices/` | 開発機の NixOS / nix-darwin 構成。共通部分は `devices/common/` | One Toolchain | -| `home-manager/modules/` | Claude Code の配布・メモリ・機密・tmux・crit。`zsh/` に Issue 駆動の関数 | One Source・Deciding and Building | -| `.claude/settings.json`・`.claude/hooks/` | deny とフック | Blocks Are Mechanisms | -| `.claude/skills/` | 手順と基準。一覧は [.claude/skills/README.md](.claude/skills/README.md) | 全節 | -| `secrets-agents/` | 対応表の復号先（`example.md` はサンプル） | Secrets | -| `issues/` | このリポジトリ自身の Issue と PR の控え | Deciding and Building | +| `flake.nix`・`devices/` | 開発機の NixOS / nix-darwin 構成。共通部分は `devices/common/` | 全端末で道具を揃える | +| `home-manager/modules/` | Claude Code の配布・メモリ・機密・tmux・crit。`zsh/` に Issue 駆動の関数 | 規則を1か所から全セッションへ配る・決める役と作る役を分ける | +| `.claude/settings.json`・`.claude/hooks/` | deny とフック | 禁止は頼まず仕組みに置く | +| `.claude/skills/` | 手順と基準。一覧は [.claude/skills/README.md](.claude/skills/README.md) | Rules Live in the Environment 全体 | +| `secrets-agents/` | 対応表の復号先（`example.md` はサンプル） | 機密を地の文に出さない | +| `issues/` | このリポジトリ自身の Issue と PR の控え | 決める役と作る役を分ける |