diff --git a/.claude/skills/README.md b/.claude/skills/README.md index bc70982..f78701a 100644 --- a/.claude/skills/README.md +++ b/.claude/skills/README.md @@ -2,6 +2,26 @@ このリポジトリは、稼働中の dotfiles から公開する分だけを抜き出したものである。写像ではないので、稼働側にあって公開側に無いことは欠陥ではない。 +## 一覧 + +基準と手順は、それを使う skill が持つ。独立したガイドの MD は置かず、skill に寄せきれないもの（複数の skill が読む `repo-standardize/reference/cicd.md`、フックの書き方の `../hooks/README.md`）だけを MD として残す。 + +| 領域 | skill | 持つもの | +|---|---|---| +| 型の判定 | [repo-standardize](repo-standardize/SKILL.md) | リポ類型と検証手段・settings.json・CLAUDE.md と context/・ファイル衛生。CI/CD は [reference/cicd.md](repo-standardize/reference/cicd.md) | +| | [repo-readme](repo-readme/SKILL.md) | README の種別判定（Type A / B / C）・下限・コアメッセージ・アウトライン | +| | [module-dev](module-dev/SKILL.md) | モジュール型リポの型・境界・デモ | +| | [mermaid-diagram](mermaid-diagram/SKILL.md) | 図を描くかの判断・幅の制約・形と線種 | +| 知識の置き場 | [skill-dev](skill-dev/SKILL.md) | 置き場の基準・自動発火の絞り方・探索の分け方 | +| | [consolidate-rules](consolidate-rules/SKILL.md) | 規則同士の矛盾・陳腐化の棚卸し | +| 保証 | [guarantee-audit](guarantee-audit/SKILL.md) | テスト方針（GDD）・保証台帳の敷設と棚卸し | +| | [mvp-docs](mvp-docs/SKILL.md) | 立ち上げ期の PLAN.md / JUDGE.md | +| 分業 | [new-issue](new-issue/SKILL.md) | フェーズ・担当分離・例外の3経路・Issue の設計 | +| | [pr-workflow](pr-workflow/SKILL.md) | 実行者の実装からローカルコミットまで | +| | [session-nudge](session-nudge/SKILL.md) | 別セッションを外から客観視する相談 | +| 公開 | [readme-i18n](readme-i18n/SKILL.md)・[repo-publish](repo-publish/SKILL.md)・[repo-about](repo-about/SKILL.md) | 英語版 README・公開手続き・About と topics | +| 前提 | [nix-tool-install](nix-tool-install/SKILL.md)・[sops-secrets](sops-secrets/SKILL.md)・[jp-writing](jp-writing/SKILL.md) | Nix 経由の導入・機密の暗号化・日本語の文章規範 | + ## 公開の基準 稼働側の skill（と、それを動かす hooks・zsh・home-manager モジュール）を公開側に置くのは、次の3問に全て「はい」と答えられるときだけ。 diff --git a/README.en.md b/README.en.md index d057dd6..5b146ea 100644 --- a/README.en.md +++ b/README.en.md @@ -4,103 +4,89 @@ [![CI](https://github.com/yktsnet/dotfiles-public/actions/workflows/ci.yml/badge.svg)](https://github.com/yktsnet/dotfiles-public/actions/workflows/ci.yml) -In development with AI agents, the bottleneck shifts from generation to verification and intent transfer. -This repository publishes a personal development environment built on that premise, as code: the Nix configuration, the machinery for role separation, and the skill set. -The development method itself is packaged for team repositories in [sdlc-kit](https://github.com/yktsnet/sdlc-kit). This repository is the environment where that method actually runs. +A personal development environment for handing development to AI agents, published as a Nix configuration together with the rules it enforces. +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. --- -## Principles (Order of Adoption) +## From Writing to Checking -The premise underneath everything is **not relying on a human who stays attentive**. Rules depend on the reader's concentration, and concentration drops with fatigue. Prohibitions live in mechanisms rather than documents, CI reruns the same checks as local verification, and the person who broke something (the Builder) gets a path to notice before submitting. +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. -Adoption is stacked in this order: +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. -1. **Decide the type before building** — classify the repo, the README, and the module, and derive every later rule from that -2. **Put prohibitions in mechanisms, not documents** — `settings.json` deny rules and PreToolUse hooks -3. **Place knowledge where it gets read** — rules that always apply in CLAUDE.md; procedures and criteria with a statable trigger in skills -4. **Approve the guarantees first** — the guarantee ledger and its tests (GDD) -5. **Separate the one who decides from the one who builds** — the three roles: Consultant, Builder, and user +--- -The order has dependencies. Without a type, you cannot decide what to block; adding knowledge before blocking only speeds up accidents. Splitting roles before the guarantees are fixed sends the Builder off without knowing what it must not break. **The minimal setup is steps 1–3**, needed regardless of publication or team size. Steps 4–5 are added once there are published artifacts or several sessions running in parallel. +## Rules Live in the Environment ---- +Rules are sorted by where they live. Rules that apply every time go in CLAUDE.md, procedures and criteria whose trigger can be stated as "when doing X" go in skills, and anything that must not be crossed goes in the `settings.json` deny list and hooks. All of it is then distributed through Nix, so the same rules apply in any repository on any machine. -## Development Lifecycle (Two Driving Documents) +### One Toolchain on Every Machine -Development is split into two phases, and the driving document changes with the phase: PLAN.md / JUDGE.md (SDD) during bootstrap, and the guarantee ledger `docs/guarantees.md` with its tests (GDD) after release. Each repository declares its phase in its CLAUDE.md. +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. -The rationale is in sdlc-kit's [docs/lifecycle.md](https://github.com/yktsnet/sdlc-kit/blob/main/docs/lifecycle.md). For the operating rules in this repository, see [guarantee-audit](.claude/skills/guarantee-audit/SKILL.md). +| Configuration | OS | Role | +|---|---|---| +| `linux-desktop` | NixOS (disko / SSD) | Primary dev machine. Where consultant chat and `issue` are launched | +| `macbook` | macOS (nix-darwin) | Shares the home-manager layer with the Linux machine | ---- +OS differences are confined to `pkgs.stdenv.isDarwin` on the Nix side and to the shims in `os.sh` (`_is_darwin`, `_sed_i`, `_open`, `_linux_only`) on the shell side; everything else is the same file on both. When an agent reaches for `brew` or `npm -g`, `block-non-nix-install.sh` stops it and points to the Nix procedure ([nix-tool-install](.claude/skills/nix-tool-install/SKILL.md)). -## Role Separation +### Blocks Are Mechanisms, Not Requests -The execution machinery for the two workflows above. Responsibilities are strictly defined across humans, conversational AI, and autonomous AI agents, so that no agent edit reaches the main branch or production without review. +`rebuild` commands, edits to `flake.lock`, `ssh`, and reading or writing the secrets mapping are closed off by deny rules. Deny rules only match string prefixes, so anything that has to be judged as an action, such as a path-qualified `/tmp/venv/bin/pip install` or rewriting `~/.claude` through `sed -i`, is handled by [PreToolUse hooks](.claude/hooks/). -* **WebChat (Design / Conversational AI)**: - In dialogue with the user, formulates specifications and design files during the MVP phase, and performs investigation and Issue design during the Issue-driven phase. Never implements. -* **AI Agent (Implementation / Autonomous AI)**: - Autonomously executes code editing, test implementation, static error checking, and local commits using Issue files as input; it never touches the remote. The procedure is fixed in [pr-workflow](.claude/skills/pr-workflow/SKILL.md). Destructive commands such as `rebuild` and access to secrets are blocked by the deny list in `.claude/settings.json`, and whatever a string prefix cannot decide (path-qualified package installs, edits to generated output) is handled by the PreToolUse hooks in [`.claude/hooks/`](.claude/hooks/). -* **User (Approval, Verification / Human)**: - Approves the guarantee sections of Issues, reviews and verifies the agent's commits locally, then publishes them (push, PR creation, merge) via `issue-finish`. Only reviewed changes ever reach the remote. +Each hook's rejection message states both why it stopped and the correct route. A rejected agent tries something else, and what it tries comes from the message, so it takes the route written there. `static-check.sh`, which syntax-checks the single file right after each edit, follows the same idea: it takes a check that nobody would notice being skipped out of the model's discretion. -Hand-offs between roles are performed by Zsh macros: +### One Source for Every Session -* **`issue`**: Selects the target Issue, creates an isolated worktree, and launches the agent inside it. The main checkout stays clean, and multiple Issues can run in parallel. -* **`issue-abort`**: Discards an in-progress worktree together with its work branch. -* **`issue-finish`**: Runs push → PR creation → merge → cleanup for a reviewed branch in one pass. +The settings, hooks, and skills in `.claude/`, together with `home-manager/config/claude/common.md`, are the source of truth. `home-manager/modules/claude.nix` copies them into `~/.claude` on every rebuild. Since `~/.claude` is a generated artifact, `block-live-claude-config-edit.sh` rejects direct edits there and returns the source path instead. -Exceptions keep the separation from becoming rigid: real-time ops such as incident response, one-off exceptions the user declares explicitly, and a lightweight route that lets small, logic-free changes through without an Issue. +As rules accumulate, they start to contradict each other. [consolidate-rules](.claude/skills/consolidate-rules/SKILL.md) audits only what changed since the last inventory point (a one-line anchor in `.claude/RULES.md`). Persistent memory lives directly under `~/memory/`, one fact per file, and `memory.nix` puts it on the git path so every machine sees the same set. -This role separation describes the flow of a single Issue; in practice, multiple worktrees and consultant sessions run in parallel. A session running on the same model and the same rules cannot detect on its own that it has drifted off course. `M-m` ([session-nudge](.claude/skills/session-nudge/SKILL.md)) provides that external reader: it sends via cross-session messaging, but only after the user approves the draft message. It never intervenes in another session automatically. +### Deciding and Building Are Separate -See [new-issue](.claude/skills/new-issue/SKILL.md) for details. +When the same model both decides and builds, it cannot notice on its own that it has gone off course. The work is split into three roles. ---- +- **Consultant**: designs the spec and the Issue in dialogue with the user. Does not implement ([new-issue](.claude/skills/new-issue/SKILL.md)) +- **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 -## Foundation (Prerequisites for Autonomous Execution) +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). -Autonomous agent execution only works once three things are structurally in place: environment, secrets, and knowledge. +[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. -* **Environment consistency via Nix**: Environment differences cause "command not found" and runtime errors for agents. Nix Flakes and Home Manager unify the macOS / Linux toolchain as code, continuously verified by CI (`nix flake check`). Installs that bypass this route (`brew`, `npm -g`, and the like) are blocked by `.claude/hooks/block-non-nix-install.sh`. -* **Secrets isolation**: Production IPs, ports, and real hostnames never appear in code or Issue files on the public repository. Actual values are isolated in the local `secrets-agents/` directory, and prose uses `` instead. The dictionary itself isn't kept as local plaintext — it's encrypted and distributed via git, and each device decrypts it with its own key. Without that, a device other than the one holding the plaintext copy would have no way to know what to mask. -* **Making tacit knowledge explicit as skills**: When "which file to hand the AI and when" depends on human tacit knowledge, the AI cannot reproduce operations alone. Any procedure statable as "when doing X" becomes a skill with its trigger condition declared in the description. The workflows in the previous section (`new-issue`, `guarantee-audit`, etc.) are committed in this form. The placement criteria live in [skill-dev](.claude/skills/skill-dev/SKILL.md). -* **Auditing the rules**: CLAUDE.md, skills, and memory all share one structure — rules a human wrote, read by an AI — and none of them detects contradictions between rules. Left alone, an ever-growing rule set destabilizes behavior, so [`consolidate-rules`](.claude/skills/consolidate-rules/SKILL.md) audits on a schedule only the diff since the last audit point (a single anchor line in `.claude/RULES.md`). Persistent memory carries no index at all: one fact per file, directly under `~/memory/`, kept at a granularity where `ls` is the index. +### Secrets Stay Out of the Prose ---- +Issues, PRs, and commit messages use `` instead of IPs, ports, and real hostnames. The mapping between real values and placeholders lives in `secrets-agents/`, which agents are not allowed to read or write. -## Devices +If the mapping existed on only one machine, writing on any other machine would mean not knowing what to mask. The mapping is encrypted with sops (age) and distributed through git, and each machine decrypts it with its own key ([sops-secrets](.claude/skills/sops-secrets/SKILL.md)). -A single Flake binds the macOS and Linux development machines. Device names are replaced with role-based generics for publication. +--- -| Configuration | OS | Role | -|---|---|---| -| `linux-desktop` | NixOS (disko / SSD) | Primary dev machine. Where consultant chat and `issue()` are launched | -| `macbook` | macOS (nix-darwin) | Shares the home-manager layer with the Linux machine | +## What Ships to sdlc-kit -OS differences are confined to `pkgs.stdenv.isDarwin` on the Nix side and to the shims in `home-manager/modules/zsh/functions/os.sh` (`_is_darwin`, `_sed_i`, `_open`, `_linux_only`) on the shell side. Home Manager modules and function files are read as-is by both operating systems. +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). -What is published is limited to the layers involved in developing with agents (Claude Code, memory, secrets, review, tmux session management). Editor and desktop settings and server configurations are not included. +Unifying tools through Nix, distributing `~/.claude`, decrypting the mapping, and persistent memory are tied to the machine, so a team repository cannot enforce them. They stay in this repository. --- -## Skills +## What Is Not Here + +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. + +--- -Criteria and procedures are held by the skill that uses them. There are no standalone guide documents; only what cannot be folded into a skill stays as a separate file (`repo-standardize/reference/cicd.md`, read by several skills, and `.claude/hooks/README.md` on how to write hooks). The criteria for what gets published are in [.claude/skills/README.md](.claude/skills/README.md). Skills are written in Japanese. +## Repository Map -| Area | Skill | What it holds | +| Path | Contents | Section | |---|---|---| -| Deciding the type | [repo-standardize](.claude/skills/repo-standardize/SKILL.md) | Repo categories and verification, settings.json, CLAUDE.md and context/, file hygiene. CI/CD in [reference/cicd.en.md](.claude/skills/repo-standardize/reference/cicd.en.md) | -| | [repo-readme](.claude/skills/repo-readme/SKILL.md) | README type (A / B / C), floor, core message, outline | -| | [module-dev](.claude/skills/module-dev/SKILL.md) | Module-repo types, boundaries, demos | -| | [mermaid-diagram](.claude/skills/mermaid-diagram/SKILL.md) | Whether to draw, width limits, shapes and line types | -| Placing knowledge | [skill-dev](.claude/skills/skill-dev/SKILL.md) | Placement criteria, narrowing auto-invocation, splitting out exploration | -| | [consolidate-rules](.claude/skills/consolidate-rules/SKILL.md) | Auditing rules for contradictions and staleness | -| Guarantees | [guarantee-audit](.claude/skills/guarantee-audit/SKILL.md) | Test policy (GDD), laying and auditing the guarantee ledger | -| | [mvp-docs](.claude/skills/mvp-docs/SKILL.md) | PLAN.md / JUDGE.md during bootstrap | -| Role separation | [new-issue](.claude/skills/new-issue/SKILL.md) | Phases, role separation, the three exception routes, Issue design | -| | [pr-workflow](.claude/skills/pr-workflow/SKILL.md) | The Builder's flow from implementation to local commit | -| | [session-nudge](.claude/skills/session-nudge/SKILL.md) | Consulting on another session from the outside | -| Publishing | [readme-i18n](.claude/skills/readme-i18n/SKILL.md), [repo-publish](.claude/skills/repo-publish/SKILL.md), [repo-about](.claude/skills/repo-about/SKILL.md) | English README, going public, About and topics | -| Prerequisites | [nix-tool-install](.claude/skills/nix-tool-install/SKILL.md), [sops-secrets](.claude/skills/sops-secrets/SKILL.md), [jp-writing](.claude/skills/jp-writing/SKILL.md) | Installing via Nix, encrypting secrets, Japanese writing rules | +| `flake.nix`, `devices/` | NixOS / nix-darwin configurations for the dev machines. Shared parts in `devices/common/` | One Toolchain | +| `home-manager/modules/` | Claude Code distribution, memory, secrets, tmux, crit. Issue-driven functions in `zsh/` | One Source, Deciding and Building | +| `.claude/settings.json`, `.claude/hooks/` | Deny rules and hooks | Blocks Are Mechanisms | +| `.claude/skills/` | Procedures and criteria. Index in [.claude/skills/README.md](.claude/skills/README.md) | All sections | +| `secrets-agents/` | Where the mapping is decrypted (`example.md` is a sample) | Secrets | +| `issues/` | This repository's own Issues and PR records | Deciding and Building | diff --git a/README.md b/README.md index 792ba56..9377678 100644 --- a/README.md +++ b/README.md @@ -4,103 +4,89 @@ [![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 構成・ロール分離の実行機構・skill 群ごとコードとして公開する。 -開発の型は、チームのリポジトリへ取り込める形に切り出して [sdlc-kit](https://github.com/yktsnet/sdlc-kit) で配っている。ここはその型を実際に回している環境である。 +AI エージェントに開発を任せる個人の開発環境を、守らせたい規則ごと Nix 構成として公開したものです。 +チームのリポジトリへ持ち込める分は [sdlc-kit](https://github.com/yktsnet/sdlc-kit) に切り出していて、ここはその型を実際に回している環境にあたります。 --- -## Principles（導入順序） +## From Writing to Checking -通底する前提は**注意し続ける人間を前提にしない**こと。規約は読み手の集中力に依存し、集中力は疲れると落ちる。禁止は文書でなく機構に置き、CI はローカル検証と同じものを二重に回し、壊したことには壊した本人（実行者）が提出前に気づく経路を用意する。 +エージェントに書かせる量が増えるにつれて、自分の仕事は書くことから確かめることへ移っていった。確かめるものが増えると、確かめ方が日によって揺れる。疲れた日は見落とし、急ぐ日は手順を飛ばす。エージェントも同じで、前のセッションで守れた規則を次のセッションでは読み落とす。 -導入は次の順に積む。 +そこで、守らせたいことを、頼んで守ってもらう文書から、外れようのない環境の側へ少しずつ移してきた。人にもエージェントにも、覚えていることを求めない。 -1. **作る前に型を決める** — リポの類型・README の種別・モジュールの型を判定し、以降の規定をそこから導く -2. **禁止を文書でなく仕組みに置く** — `settings.json` の deny と PreToolUse フック -3. **読まれる場面ごとに知識を置く** — 毎回効く規則は CLAUDE.md、条件を言える手順と基準は skill -4. **守る保証を先に裁可する** — 保証台帳とテスト（GDD） -5. **決める人と作る人を分ける** — 相談者・実行者・user の三役 +--- -順序には依存がある。型が決まらないと何を遮断すべきかが決まらず、遮断が無いまま知識を増やすと事故の速度だけが上がる。保証が固まる前に分業すると、実行者は何を壊してはいけないか分からないまま走る。**最小構成は 1〜3** で、公開の有無やチーム規模に関わらず要る。4〜5 は公開物を持つとき、または複数セッションで並行し始めたときに足す。 +## Rules Live in the Environment ---- +規則は置き場で分けています。毎回守らせる規則は CLAUDE.md、「〜するとき」と条件を言える手順と基準は skill、外れてはいけないものは `settings.json` の deny とフックに置きます。そのうえで、どのリポジトリ、どの端末で開いても同じものが効くように、全部を Nix で配ります。 -## Development Lifecycle（2つの駆動文書） +### One Toolchain on Every Machine -開発を2フェーズに分け、駆動文書を交代させる。立ち上げ期は PLAN.md / JUDGE.md（SDD）、リリース後は保証台帳 `docs/guarantees.md` とテスト（GDD）で回す。フェーズは各リポジトリの CLAUDE.md で宣言する。 +macOS と Linux の開発機を1つの Flake で管理しています。端末ごとに道具の有無や版が違うと、エージェントは「コマンドが無い」「動きが違う」で止まり、止まった理由の調査に人の時間を取られます。 -考え方は sdlc-kit の [docs/lifecycle.md](https://github.com/yktsnet/sdlc-kit/blob/main/docs/lifecycle.md) にある。本リポジトリでの運用基準は [guarantee-audit/SKILL.md](.claude/skills/guarantee-audit/SKILL.md) を参照。 +| 構成 | 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)）へ案内します。 -## Role Separation（ロールの分離） +### Blocks Are Mechanisms, Not Requests -上記2ワークフローの実行機構。人間、対話型AI、自律型AIエージェントの担当範囲を厳格に定義し、エージェントの編集がレビューを経ないままメインブランチや本番に及ばないようにする。 +`rebuild` 系・`flake.lock` の編集・`ssh`・機密の対応表の読み書きは deny で塞いでいます。deny は文字列の前方一致しか見ないので、`/tmp/venv/bin/pip install` のようなパス付きの実行や、`~/.claude` を `sed -i` で書き換えるような、行為として判定が要るものは [PreToolUse フック](.claude/hooks/)で扱います。 -* **WebChat（設計・対話型AI）**: - ユーザーと対話しながら、MVP期は仕様策定と設計ファイルの作成を、Issueドリブン期は調査と Issue 設計を行う。実装はしない。 -* **AI Agent（実装・自律型AI）**: - Issue ファイルをインプットとしてコード編集・テスト実装・静的エラー確認・ローカルコミットまでを自律実行し、リモートには触れない。手順は [pr-workflow](.claude/skills/pr-workflow/SKILL.md) に固定してある。`rebuild` 等の破壊的コマンドや機密へのアクセスは `.claude/settings.json` の deny で遮断し、前方一致では判定できないもの（パス付き実行のパッケージ導入、生成物への直接編集）は [`.claude/hooks/`](.claude/hooks/) の PreToolUse フックが受け持つ。 -* **User（裁可・検証・人間）**: - Issue の保証節を裁可し、エージェントのコミットをローカルでレビュー・動作確認し、`issue-finish` で公開（push・PR作成・マージ）を実行する。レビューを通った変更だけがリモートに残る。 +フックの拒否文には、止めた理由と正しい経路を両方書きます。エージェントは拒否されると別の手を試すので、拒否文に書いた経路へそのまま進みます。編集直後に1ファイルだけ構文検査する `static-check.sh` も同じ考えで、忘れても誰も気づかない確認を、モデルの裁量から外しています。 -ロール間の受け渡しは Zsh マクロで行う: +### One Source for Every Session -* **`issue`**: 対象 Issue を選択し、worktree を隔離作成してエージェントを起動。main を汚さず複数 Issue を並列実行できる。 -* **`issue-abort`**: 進行中の worktree を作業ブランチごと破棄。 -* **`issue-finish`**: レビュー済みブランチの push → PR 作成 → マージ → 後片付けを一括実行。 +`.claude/` の settings・hooks・skills と `home-manager/config/claude/common.md` が正本で、`home-manager/modules/claude.nix` が rebuild のたびに `~/.claude` へ実体コピーします。`~/.claude` 側は生成物になるので、そこを直接編集しようとすると `block-live-claude-config-edit.sh` が止め、正本のパスを返します。 -分離を硬直させないための例外も定義している。障害対応などのリアルタイム ops、user が明示宣言する単発例外、そしてロジックに触れない小規模変更を Issue 化なしで通す軽量経路の3経路である。 +規則が増えると、規則同士が食い違い始めます。[consolidate-rules](.claude/skills/consolidate-rules/SKILL.md) が前回の棚卸し地点（`.claude/RULES.md` のアンカー1行）からの差分だけを監査します。永続メモリは `~/memory/` 直下に1ファイル1事実で置き、`memory.nix` で git の経路に乗せて端末間で揃えます。 -このロール分離は1本の Issue の流れを説明したものであり、実際には複数の worktree と相談者セッションが同時に走る。同じモデル・同じ規則で動くセッションは、自分が方向を外したことを自分では検出できない。外部の読み手を用意するのが `M-m`（[session-nudge](.claude/skills/session-nudge/SKILL.md)）で、送信は cross-session messaging で行うが、文案は必ず user が承認してから送る。自動で他セッションへ介入はしない。 +### Deciding and Building Are Separate -詳細は [new-issue](.claude/skills/new-issue/SKILL.md) を参照。 +同じモデルが決めて作ると、方向を外したことに自分では気づけません。役割を3つに分けています。 ---- +- **相談者**: user と対話して仕様と Issue を設計する。実装はしない（[new-issue](.claude/skills/new-issue/SKILL.md)） +- **実行者**: Issue を入力に、実装・テスト・ローカルコミットまでを進める。リモートには触れない（[pr-workflow](.claude/skills/pr-workflow/SKILL.md)） +- **user**: Issue の保証節を裁可し、コミットをレビューして公開する -## Foundation（自律実行の前提条件） +受け渡しは zsh の関数で行います。`issue` が worktree を切って実行者を起動し、`issue-finish` がレビュー済みのブランチを push から PR・マージ・後片付けまで進め、`issue-abort` は worktree をブランチごと捨てます。worktree ごとに隔離されるので、複数の Issue を並行して走らせられます。実行者の変更は [crit](https://github.com/tomasz-tomczyk/crit) で行単位にレビューします。 -エージェントの自律実行は、環境・機密・知識の3点を構造的に整えてはじめて成立する。 +並行するセッションの外に立つ読み手として [session-nudge](.claude/skills/session-nudge/SKILL.md) があり、別セッションへの助言を、文案を user が承認してから送ります。障害対応のような即時の作業、user が明示した単発の例外、ロジックに触れない小さな変更は、Issue を立てずに通します。 -* **Nix による環境同一性**: 環境差はエージェントの「コマンド未検出」「実行時エラー」を招く。Nix Flakes と Home Manager で macOS / Linux のツールチェーンをコードとして同一化し、CI（`nix flake check`）で継続検証する。導入経路の逸脱（`brew` / `npm -g` / `pip install`）は `.claude/hooks/block-non-nix-install.sh` が遮断する。 -* **機密情報の分離**: 公開リポジトリ側のコードや Issue ファイルに本番の IP・ポート・実ホスト名を書かない。実値はローカルの `secrets-agents/` に隔離し、地の文では `` を用いる。辞書は平文でローカルに置くのではなく暗号化して git 経由で配り、各デバイスが自分の鍵で復号する。1台にしか無いと、別のデバイスでは何を伏せるべきか分からないまま書くことになるため。 -* **暗黙知の skill 化**: 「どのファイルをいつ AI に渡すか」が人間の暗黙知に依存すると、AI 単独で運用を再現できない。「〜するとき」と条件を言える手順は skill 化し、description に起動条件を宣言する。前節のワークフロー自体（`new-issue`・`guarantee-audit` 等）もこの形でコミットされている。置き場の基準は [skill-dev](.claude/skills/skill-dev/SKILL.md) が持つ。 -* **規則の棚卸し**: CLAUDE.md も skill も memory も「人が書いた規則を AI が読む」構造であり、規則同士の矛盾を検出する仕組みを持たない。増え続ける規則を放置すると挙動が不安定になるため、[`consolidate-rules`](.claude/skills/consolidate-rules/SKILL.md) が前回の棚卸し地点（`.claude/RULES.md` のアンカー1行）からの差分だけを定期監査する。永続メモリは索引を持たせず、`~/memory/` 直下に1ファイル1事実で置く（`ls` が索引になる粒度に保つ）。 +### Secrets Stay Out of the Prose ---- +Issue・PR・コミットの地の文には、IP・ポート・実ホスト名を書かずに `` を使います。実値とプレースホルダの対応表は `secrets-agents/` に置き、エージェントからは読み書きさせません。 -## Devices（管理対象） +対応表が1台にしか無いと、別の端末では何を伏せるべきか分からないまま書くことになります。対応表は sops（age）で暗号化して git で配り、各端末が自分の鍵で復号します（[sops-secrets](.claude/skills/sops-secrets/SKILL.md)）。 -単一の Flake が macOS と Linux の開発機を束ねる。デバイス名は公開にあたり役割ベースの総称に置き換えている。 +--- -| 構成 | OS | 役割 | -|---|---|---| -| `linux-desktop` | NixOS（disko / SSD） | 主開発機。相談者チャットと `issue()` の起動元 | -| `macbook` | macOS（nix-darwin） | home-manager 層を Linux 機と共有する | +## What Ships to sdlc-kit -OS の差は、Nix 側では `pkgs.stdenv.isDarwin`、シェル側では `home-manager/modules/zsh/functions/os.sh` のシム（`_is_darwin` / `_sed_i` / `_open` / `_linux_only`）に閉じ込める。home-manager モジュールと関数ファイルは両 OS が同一のものを読む。 +ここで回している型のうち、チームのリポジトリへ持ち込めるものを [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) にあります。 -公開しているのは、エージェントとの開発に関わる層（Claude Code・メモリ・機密・レビュー・tmux のセッション管理）に限る。エディタやデスクトップの設定、サーバー類の構成は含めていない。 +Nix による道具の統一、`~/.claude` の配布、対応表の復号、永続メモリは端末に紐づくので、チームのリポジトリからは効かせられません。これらはこのリポジトリに残ります。 --- -## Skills +## What Is Not Here + +稼働中の dotfiles から、エージェントとの開発に関わる層（Claude Code・メモリ・機密・レビュー・tmux のセッション管理）だけを抜き出しています。エディタやデスクトップの設定、サーバー類の構成は含めていません。抜き出しであって写しではないので、稼働側にあってここに無いものがあります。何を公開するかの基準は [.claude/skills/README.md](.claude/skills/README.md) にあります。 + +clone して各自の端末へ適用することは想定していません。デバイス構成は実機のハードウェアと鍵を前提にしていて、`secrets/` の暗号文も含めていません。CI の `nix flake check` は、公開している構成が評価できる状態にあることを確かめています。 + +--- -基準と手順は、それを使う skill が持つ。独立したガイドの MD は置かず、skill に寄せきれないもの（複数の skill が読む `repo-standardize/reference/cicd.md`、フックの書き方の `.claude/hooks/README.md`）だけを MD として残す。何を公開するかの基準は [.claude/skills/README.md](.claude/skills/README.md)。 +## Repository Map -| 領域 | skill | 持つもの | +| パス | 中身 | 対応する節 | |---|---|---| -| 型の判定 | [repo-standardize](.claude/skills/repo-standardize/SKILL.md) | リポ類型と検証手段・settings.json・CLAUDE.md と context/・ファイル衛生。CI/CD は [reference/cicd.md](.claude/skills/repo-standardize/reference/cicd.md) | -| | [repo-readme](.claude/skills/repo-readme/SKILL.md) | README の種別判定（Type A / B / C）・下限・コアメッセージ・アウトライン | -| | [module-dev](.claude/skills/module-dev/SKILL.md) | モジュール型リポの型・境界・デモ | -| | [mermaid-diagram](.claude/skills/mermaid-diagram/SKILL.md) | 図を描くかの判断・幅の制約・形と線種 | -| 知識の置き場 | [skill-dev](.claude/skills/skill-dev/SKILL.md) | 置き場の基準・自動発火の絞り方・探索の分け方 | -| | [consolidate-rules](.claude/skills/consolidate-rules/SKILL.md) | 規則同士の矛盾・陳腐化の棚卸し | -| 保証 | [guarantee-audit](.claude/skills/guarantee-audit/SKILL.md) | テスト方針（GDD）・保証台帳の敷設と棚卸し | -| | [mvp-docs](.claude/skills/mvp-docs/SKILL.md) | 立ち上げ期の PLAN.md / JUDGE.md | -| 分業 | [new-issue](.claude/skills/new-issue/SKILL.md) | フェーズ・担当分離・例外の3経路・Issue の設計 | -| | [pr-workflow](.claude/skills/pr-workflow/SKILL.md) | 実行者の実装からローカルコミットまで | -| | [session-nudge](.claude/skills/session-nudge/SKILL.md) | 別セッションを外から客観視する相談 | -| 公開 | [readme-i18n](.claude/skills/readme-i18n/SKILL.md)・[repo-publish](.claude/skills/repo-publish/SKILL.md)・[repo-about](.claude/skills/repo-about/SKILL.md) | 英語版 README・公開手続き・About と topics | -| 前提 | [nix-tool-install](.claude/skills/nix-tool-install/SKILL.md)・[sops-secrets](.claude/skills/sops-secrets/SKILL.md)・[jp-writing](.claude/skills/jp-writing/SKILL.md) | Nix 経由の導入・機密の暗号化・日本語の文章規範 | +| `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 | diff --git a/context/structure.md b/context/structure.md index 573a4dc..45c4a81 100644 --- a/context/structure.md +++ b/context/structure.md @@ -34,7 +34,7 @@ dotfiles-public/ - **ユーザ環境層**: `home-manager/`。エージェント関連（Claude Code・メモリ・機密・tmux のセッション管理等）を宣言的に管理。 - **ワークフロー層**: `home-manager/modules/zsh/functions/`。`issue` / `issue-abort` / `issue-finish` 等のマクロ。 - **ハーネス層**: `.claude/`。`settings.json` の deny（前方一致で足りるもの）と `hooks/` の PreToolUse（コマンド構造・編集先の判定が要るもの）で遮断を二段に分ける。`skills/` が正本で、`home-manager/modules/claude.nix` が `~/.claude/` へ配置する。 -- **基準と道具**: 判断の基準と、それを実行するスクリプトは、使う skill が持つ（`sops-secrets/scripts/inject.py`、`guarantee-audit/reference/guarantees-index/` 等）。導入順序と前提は README の Principles 節。公開の基準は `.claude/skills/README.md`。 +- **基準と道具**: 判断の基準と、それを実行するスクリプトは、使う skill が持つ（`sops-secrets/scripts/inject.py`、`guarantee-audit/reference/guarantees-index/` 等）。規則の置き場の分け方は README の Rules Live in the Environment 節。公開の基準は `.claude/skills/README.md`。 - **機密層**: `secrets/` が暗号文、`secrets-agents/` が各機で復号したマスク辞書。どちらも Agent からは読み書きしない。 ## issues/