## バージョン管理 — 必須手順

このプロジェクトは **Jujutsu (jj)** でバージョン管理している。詳細なルールは `.claude/rules/jujutsu-rules.md` を参照のこと。

**コードの編集を始める前に**、今回の作業をどの change に属させるか必ず確定する必要がある。working-copy commit (`@`) を確認して、空であればそのまま再利用し、空でなければ新しい change を作成する。判断手順はルールファイル「基本ワークフロー」の「1. 作業を始める」に記載されている。先に編集を始めて、後から change を整理してはいけない。

**禁止事項:** `git` コマンドの直接使用（`jj git` サブコマンドおよび `gh` CLI は許可）

# Jujutsu (jj) Rules for AI Agents

jj の標準的なセマンティクスは AI エージェントにとって既知のものと想定する。ここに記述するのはそこから推察しえない、Jujutsu ネイティブのワークフロー、およびリポジトリ固有の設定やエイリアスを前提とした手順である。

---

## AI エージェントへの重要な注意

### コマンドの制約

以下は `settings.json` で明示的に禁止されている。これらを前提にしたプランを立ててはならない。どうしても必要な場合は、コマンドを提示してユーザー自身に実行してもらうこと。

| 禁止コマンド  | 理由                                                                  |
| ------------- | --------------------------------------------------------------------- |
| `git`（全般） | jj の状態を壊すおそれがある。`jj git ...` と `gh` は引き続き使用可。  |
| `jj resolve`  | マージエディタが開く。conflict はファイルを直接編集して解消する。     |
| `jj diffedit` | diff エディタが開く。                                                 |
| `jj arrange`  | 対話的な TUI。                                                        |

`jj split` は使用できるが、**必ず fileset と `-m` を渡すこと。引数なしでの実行、および `-i` と `--tool` の指定は、diff エディタが起動してしまうためいずれも禁止。**

また次のコマンドは実行のたびにユーザーへの確認が必要になる。作業の途中で打つのではなく、タスクの終盤にまとめること。
`jj git push`, `jj bookmark delete`, `jj bookmark forget`, `jj bookmark track`, `jj bookmark untrack`

### jj でワークフローがどう変わるか

- **staging も stash も「未保存の変更」も存在しない。** ファイルを保存した瞬間、その内容は working-copy commit（`@`）の一部になる。「この変更を含めますか？」とユーザーに尋ねてはならない。すでに含まれている。
- **bookmark は branch ではなく、`@` に追従しない。** そして追従する必要もない。作業中はその場に置いたままでよく、同期を取るべきものは何もない。実際に使う直前になってから位置を決めること（「bookmark を配置する」を参照）。

### diff 出力のルール

`jj diff`、`jj show`、`jj log -p` には必ず `--git` を付ける。付けない出力ではファイルの追加・削除・リネーム・パーミッション変更を正確に表現できず、そのぶん diff の読み取り精度が落ちる。

### 読み取り専用操作でのスナップショット抑止

jj はコマンドを実行するたびにワーキングコピーのスナップショットを取るため、同じリポジトリで別プロセスが動いているとオペレーションログで衝突するおそれがある。純粋な読み取り操作、すなわち `jj log`、`jj diff`、`jj bookmark list`、`jj evolog`、`jj op log` には `--ignore-working-copy` を付けること。

**ファイルを作成・編集・削除した直後には付けてはならない。** そこはまさにスナップショットを記録すべき場面である。他のコマンドを実行せずスナップショットだけ取りたいときは `jj util snapshot` を使う。

### log 出力の使い分け

通常の状態確認では `jj log` のグラフ表示をそのまま読む。値をプログラムから取り出すときは `--no-graph` と `-T` を付ける。

```bash
jj log --ignore-working-copy --no-graph -T 'change_id.short() ++ " " ++ description.first_line() ++ "\n"'
```

---

## 基本ワークフロー

### 1. 作業を始める

working-copy commit（`@`）の状態に応じて動きを変える。

1. `jj status` を実行する。ここでは `--ignore-working-copy` を **付けない**。上のルールに対する唯一の例外である。直前の jj コマンド以降にユーザーがファイルを編集している可能性があり、スナップショットを飛ばすとその編集が存在しないものとして報告されてしまう。
2. **`@` が空なら**（description も diff も持たない）→ **そのまま再利用する。** `jj describe -m "<description>"` で description を設定し、その中で作業する。**新しい change を作ってはならない。** `jj new` で作られた change もそれ自体は空なので、このルールに該当する。
3. それ以外（すでに description もしくは diff がある）→ `jj new -m "<description>"` を実行する。
4. description は英語の Conventional Commits 形式で書く。

### 2. change を分割する

```bash
jj split -m "<切り出す change の description>" <path>...
```

diff エディタを開かせないのは fileset、説明文エディタを開かせないのは `-m` である。hunk 単位の分割にはそのエディタが必要なので、ユーザーに委ねること。

### 3. conflict を解消する

マーカーの入ったファイルを直接編集し、`jj status` で conflict が消えたことを確認する。ファイルを保存すること自体が解消であり、その後に `git add` に相当する操作は要らない。

jj の conflict マーカーは Git のものとは異なる。`%%%%%%%` のブロックはベースからの差分を `-`/`+` の行で表したもので、`+++++++` のブロックはもう一方のそのままの内容である。

### 4. bookmark を配置する

bookmark を動かすのは、push を頼まれたときと、push の手順が暗黙に含まれる形で PR の作成を頼まれたときだけ。それ以外では触れないこと。change の存在に bookmark は必須ではない。

中身を見ないまま `@` に向けてはならない。`jj new` の直後の `@` は description のない空の change であり、description がない commit の push は拒否される。`@` の祖先のうち diff と description の両方を持つ最も新しい change を対象とし、動かす前に読み返すこと。

```bash
jj log --ignore-working-copy --no-graph \
  -r 'heads(::@ & ~empty() & ~description(exact:""))' \
  -T 'change_id.short() ++ " " ++ description.first_line() ++ "\n"'

jj bookmark create <name> -r 'heads(::@ & ~empty() & ~description(exact:""))'  # 初回
jj bookmark move <name> --to 'heads(::@ & ~empty() & ~description(exact:""))'  # 2 回目以降
```

**`jj bookmark advance` は使わないこと。** 対象を `revsets.bookmark-advance-to` から取るため、着地点がコマンドの記述ではなくリポジトリの設定で決まってしまう。呼び出す場所で対象を明示すること。

### 5. リモートと同期する

```bash
jj git fetch                      # リモートの最新状態を取得する
jj git push -b <bookmark-name>    # bookmark を push する
```

---

## PR 作成ワークフロー

- ターゲットは指示がない限り常に `main`。確認は不要。
- **squash しない。** 変更履歴の追跡可能性を保つため、各 change はそのまま残す。
- タイトルは `--title` で明示的に渡す。bookmark の先頭 change の description から導いた Conventional Commits 形式にすること。`gh` が自動生成するタイトルに任せない。

```bash
jj git fetch
jj log --ignore-working-copy
jj bookmark list --all --ignore-working-copy   # 確認後、上記の手順で配置する
jj bookmark track <bookmark-name>@origin       # 未追跡の場合のみ
jj git push -b <bookmark-name>                 # ローカルとリモートが一致していれば不要
gh pr create --base main --head <bookmark-name> --title "<type>: <summary>" --body "<body>"
```

---

## トラブルシューティング

**「The working copy is stale」** — 同じリポジトリで人間と AI が並行して作業したか、外部ツールがファイルを書き換えた場合に起きる。`jj workspace update-stale` を実行し、`jj status` で正常に戻ったことを確認する。

{
  "permissions": {
    "allow": [
      "Bash(jj status:*)",
      "Bash(jj log:*)",
      "Bash(jj diff:*)",
      "Bash(jj show:*)",
      "Bash(jj file list:*)",
      "Bash(jj root:*)",
      "Bash(jj describe:*)",
      "Bash(jj new:*)",
      "Bash(jj edit:*)",
      "Bash(jj restore:*)",
      "Bash(jj squash:*)",
      "Bash(jj rebase:*)",
      "Bash(jj abandon:*)",
      "Bash(jj evolog:*)",
      "Bash(jj op log:*)",
      "Bash(jj operation log:*)",
      "Bash(jj undo:*)",
      "Bash(jj bookmark list:*)",
      "Bash(jj bookmark create:*)",
      "Bash(jj bookmark move:*)",
      "Bash(jj bookmark advance:*)",
      "Bash(jj bookmark set:*)",
      "Bash(jj bookmark rename:*)",
      "Bash(jj git fetch:*)",
      "Bash(jj config get:*)",
      "Bash(jj config list:*)"
    ],
    "deny": [
      "Bash(git:*)",
      "Bash(jj resolve:*)",
      "Bash(jj diffedit:*)",
      "Bash(jj arrange:*)"
    ],
    "ask": [
      "Bash(jj bookmark delete:*)",
      "Bash(jj bookmark forget:*)",
      "Bash(jj bookmark track:*)",
      "Bash(jj bookmark untrack:*)",
      "Bash(jj git push:*)"
    ]
  }
}

## バージョン管理 — 必須手順

このプロジェクトはバージョン管理に Jujutsu（`jj`）を使用する。用語とコマンドは `jj` に統一し、`git` コマンドを直接実行してはならない。ただし `jj git ...` と `gh` は使用してよい。

編集を始める前に `jj status` を実行し、working copy をスナップショットに保存したうえで、working-copy commit（`@`）の状態を確認する。`@` に description と diff のどちらもない場合に限り、そのまま再利用する。それ以外の場合は、新しい change を作成する。change description は Conventional Commits に従い、英語で記述する。

`jj diff`、`jj show`、`jj log -p` には、必ず `--git` を付ける。`--ignore-working-copy` は、working copy がスナップショット済みだと確認できている場合に限り、変更を伴わない参照目的の操作にのみ使用する。

`jj resolve`、`jj diffedit`、`jj arrange` を実行してはならない。`jj split` は fileset と `-m` を必ず渡して実行する（引数なしでの実行、`-i` と `--tool` の指定はいずれも禁止）。これが差分エディタを開かせないための条件である。履歴を変更する操作を行った後は `jj status` を実行し、conflict があれば解消してから作業を続ける。

変更を公開するとき以外は、bookmark を移動しない。特に指示がない限り、PR のターゲットは `main` とする。また、stacked change を squash してはならない。

複雑な revset、conflict、bookmark の操作、履歴の書き換えや復旧、fetch、push、PR の作成については、`.agents/skills/jujutsu/SKILL.md` にある `jujutsu` Skill を参照すること。

---
name: jujutsu
description: 複雑な revset、conflict、bookmark、履歴の書き換えや復旧、リモートとの同期、PR の作成など、単純ではない Jujutsu 操作に関する、このリポジトリ固有の手順。
---

# Jujutsu の操作

常時適用される方針は `AGENTS.md` に記載している。この Skill では、標準的な Jujutsu の挙動からは導けない、このリポジトリ固有の判断基準と手順のみを扱う。

## この Skill を使用する場面

- 単純ではない revset の記述や評価
- conflict の解消
- bookmark の作成、移動、追跡、追跡解除、削除
- rebase、squash、restore、abandon、undo、操作の復元
- diff エディタを使わない change の分割
- stale working copy や immutable revision のエラーへの対処
- fetch、push、PR の作成

通常の状態確認や一般的な作業の開始には、この Skill は必要ない。`AGENTS.md` に直接従うこと。

## リポジトリ固有の制約

- `git` コマンドを直接実行してはならない。ただし `jj git ...` と `gh` は使用してよい。
- `jj resolve`、`jj diffedit`、`jj arrange` を実行してはならない。これらは対話型インターフェースを必要とする。`jj split` は fileset と `-m` を渡す形式に限り使用してよい。引数なしでの実行、`-i` と `--tool` の指定は禁止（「ファイル単位で change を分割する」を参照）。非対話型コマンドで安全に完了できない作業については、その部分をユーザーに実行してもらうこと。
- `jj diff`、`jj show`、`jj log -p` には、必ず `--git` を付ける。
- `jj new`、`jj rebase`、`jj squash`、`jj restore`、`jj abandon` など、履歴を変更する操作を行った後は、作業を続ける前に `jj status` を実行する。
- PR の準備時に stacked change を squash してはならない。

## スナップショットの規律

`--ignore-working-copy` を参照専用の確認、すなわち `jj log`、`jj diff`、`jj bookmark list`、`jj evolog`、`jj op log` に付けてよいのは、作業コピーがすでにスナップショット済みだと確認できている場合に限る。このオプションは新しいスナップショットの作成を抑止するため、古い状態を返す可能性がある。

作業の開始時、およびファイルを作成、編集、削除した直後には付けないこと。そこはまさに最新のファイルシステムの状態を取り込むべき場面である。

## ファイル単位で change を分割する

```bash
jj split -m "<切り出す change の description>" <path>...
```

diff エディタを開かせないのは fileset、テキストエディタを開かせないのは `-m` である。hunk 単位の分割にはそのエディタが必要なので、ユーザーに委ねること。

## conflict を解消する

conflict マーカーを直接編集して意図した最終内容にし、`jj status` で conflict が残っていないことを確認する。ファイルを保存すること自体が解消である。`jj resolve` を実行してはならず、編集後に `git add` 相当の操作も要らない。

## 公開する revision に bookmark を配置する

通常の実装中に bookmark を移動してはならない。ユーザーから push または PR の作成を依頼された場合にのみ、bookmark を配置する。PR の作成依頼に push が暗黙的に含まれる場合も同様である。

`@` が公開対象の revision だと決めつけてはならない。`jj new` の実行後は空の change である可能性がある。`@` の祖先のうち内容と description の両方を持つ最新の revision を対象とし、bookmark を配置する前に出力結果を確認すること。

```bash
jj log --ignore-working-copy --no-graph \
  -r 'heads(::@ & ~empty() & ~description(exact:""))' \
  -T 'change_id.short() ++ " " ++ description.first_line() ++ "\n"'

jj bookmark create <name> -r 'heads(::@ & ~empty() & ~description(exact:""))'
jj bookmark move <name> --to 'heads(::@ & ~empty() & ~description(exact:""))'
jj status
```

新しい bookmark には `create`、既存の bookmark には `move` を使用する。`jj bookmark advance` は使用せず、呼び出し箇所で対象 revision を明示する。

## リモートおよび PR のワークフロー

特に指示がない限り、PR のベースには `main` を使用し、stack 内の各 change を維持する。remote bookmark が未追跡なら `jj bookmark track <name>@origin` で追跡を開始し、local と remote が一致していれば push は不要。PR タイトルは Conventional Commits 形式で明示的に渡し、本文は日本語で書く。

```bash
jj git fetch
jj log --ignore-working-copy
jj bookmark list --all --ignore-working-copy   # 確認後、前述の手順で配置する
jj git push -b <name>
gh pr create --base main --head <name> --title "<type>: <summary>" --body "<body>"
```

## 復旧とトラブルシューティング

`jj undo`、`jj op restore`、`jj restore`、`jj abandon` を実行する前に、影響を受ける操作または revision を確認し、それが意図した対象と正確に一致することを確かめる。対象を推測したまま、ユーザーの作業を破棄したり書き換えたりしてはならない。

**stale working copy** — `jj workspace update-stale` を実行し、続けて `jj status` で確認する。

**immutable revision** — immutability を迂回してはならない。対象 revision を確認し、意図した可変 change を選んで、その change 上で操作をやり直す。

# .codex/rules/jujutsu.rules

# --- allow ---
prefix_rule(pattern = ["jj", "status"], decision = "allow")
prefix_rule(pattern = ["jj", "log"], decision = "allow")
prefix_rule(pattern = ["jj", "diff"], decision = "allow")
prefix_rule(pattern = ["jj", "show"], decision = "allow")
prefix_rule(pattern = ["jj", "file", "list"], decision = "allow")
prefix_rule(pattern = ["jj", "root"], decision = "allow")
prefix_rule(pattern = ["jj", "describe"], decision = "allow")
prefix_rule(pattern = ["jj", "new"], decision = "allow")
prefix_rule(pattern = ["jj", "edit"], decision = "allow")
prefix_rule(pattern = ["jj", "restore"], decision = "allow")
prefix_rule(pattern = ["jj", "squash"], decision = "allow")
prefix_rule(pattern = ["jj", "rebase"], decision = "allow")
prefix_rule(pattern = ["jj", "abandon"], decision = "allow")
prefix_rule(pattern = ["jj", "evolog"], decision = "allow")
prefix_rule(pattern = ["jj", "op", "log"], decision = "allow")
prefix_rule(pattern = ["jj", "operation", "log"], decision = "allow")
prefix_rule(pattern = ["jj", "undo"], decision = "allow")
prefix_rule(pattern = ["jj", "bookmark", "list"], decision = "allow")
prefix_rule(pattern = ["jj", "bookmark", "create"], decision = "allow")
prefix_rule(pattern = ["jj", "bookmark", "move"], decision = "allow")
prefix_rule(pattern = ["jj", "bookmark", "advance"], decision = "allow")
prefix_rule(pattern = ["jj", "bookmark", "set"], decision = "allow")
prefix_rule(pattern = ["jj", "bookmark", "rename"], decision = "allow")
prefix_rule(pattern = ["jj", "config", "get"], decision = "allow")
prefix_rule(pattern = ["jj", "config", "list"], decision = "allow")
prefix_rule(
    pattern = ["jj", "git", "fetch"],
    decision = "allow",
    justification = "Jujutsu の fetch は許可"
)

# --- deny / forbidden ---
prefix_rule(
    pattern = ["git"],
    decision = "forbidden",
    justification = "raw git は使わず、jj コマンドを使うこと"
)
prefix_rule(
    pattern = ["jj", "resolve"],
    decision = "forbidden",
    justification = "conflict は手動で行うこと"
)
prefix_rule(
    pattern = ["jj", "diffedit"],
    decision = "forbidden",
    justification = "jj diffedit は手動で行うこと"
)
prefix_rule(
    pattern = ["jj", "arrange"],
    decision = "forbidden",
    justification = "jj arrange は手動で行うこと"
)

# --- ask / prompt ---
prefix_rule(
    pattern = ["jj", "bookmark", "delete"],
    decision = "prompt",
    justification = "bookmark 削除は確認必須"
)
prefix_rule(
    pattern = ["jj", "bookmark", "forget"],
    decision = "prompt",
    justification = "bookmark forget は確認必須"
)
prefix_rule(
    pattern = ["jj", "bookmark", "track"],
    decision = "prompt",
    justification = "remote bookmark の追跡開始は確認必須"
)
prefix_rule(
    pattern = ["jj", "bookmark", "untrack"],
    decision = "prompt",
    justification = "remote bookmark の追跡解除は確認必須"
)
prefix_rule(
    pattern = ["jj", "git", "push"],
    decision = "prompt",
    justification = "リモートへの push は確認が必要",
    match = ["jj git push -b feature-x"],
)