jujutsu-workflow

# Jujutsu Development Workflow for AI Agents

## バージョン管理システム: Jujutsu (jj)

- **優先使用**: Jujutsu (jj) コマンドを使用
- **Git経由**: Gitコマンドは使わず、jj経由でGit操作
- **基本哲学**: Change IDで管理、ブックマークは必要な時だけ

## Jujutsuの基本原則

### Change IDベース管理
- すべてのコミットはChange IDで一意に識別
- ブックマーク（ブランチ名）は「名札」程度の位置づけ
- Gitの「すべてのコミットがブランチに属する」という考えから脱却

### ブックマークが必要なタイミング
1. **リモートプッシュ時**（最重要）
2. **チーム共有時**
3. **長期参照ポイント**

### ブックマークが不要なタイミング
- 個人で作業中
- 実験的な変更
- 一時的な作業

## ドキュメント作成のルール

### 原則：実コードとドキュメントの二重管理を避ける

**重要**: ドキュメントにコードを記述することはできるだけ避ける

**理由:**
- 実コードとドキュメントの二重管理になる
- コードが変更されてもドキュメントが更新されない
- メンテナンスコストが増加
- 不整合が発生しやすい

**推奨アプローチ:**
1. **コード例は最小限に**: 実行可能なコードはドキュメントに書かず、実ファイルへの参照を使用
2. **概念の説明に集中**: ドキュメントは「なぜ」「どうやって」を説明
3. **参照を活用**: 実コードへのリンクや参照を使用
4. **使用例は別ファイル**: サンプルコードは `examples/` ディレクトリに配置

**OK例（ドキュメント）:**
```markdown
## ユーザー認証

詳細な実装は `src/auth/authenticator.py` を参照してください。

### 使い方

使用例は `examples/auth_usage.py` を参照してください。
```

**NG例（ドキュメント）:**
```markdown
## ユーザー認証

以下のコードを使用してください：
\`\`\`python
def authenticate(username, password):
    # ... 30行のコード ...
\`\`\`
```

**例外（許可されるケース）:**
- コマンドラインの使用方法（短い1-2行のコマンド例）
- 設定ファイルの構造（小さなサンプル）
- APIエンドポイントの呼び出し例（curlコマンドなど）

## AIエージェントの必須動作ルール

### 📂 ユーザーにコマンド実行を依頼する際の作業ディレクトリ確認（必須）

**原則**: ユーザーにコマンド実行を依頼する際は、必ず以下の手順を踏むこと

#### 必須手順

1. **現在の作業ディレクトリを確認**
   - ユーザーのターミナル出力から現在位置を把握
   - または、確認コマンドを提示

2. **正しいディレクトリへの移動コマンドを最初に提示**
   - プロジェクト固有の操作は、そのプロジェクトディレクトリで実行
   - 移動コマンドを明示的に提示

3. **実際の操作コマンドを提示**
   - ディレクトリ移動後の操作を提示

#### 推奨フォーマット

```bash
# Step 0: 作業ディレクトリに移動（最優先）
cd /Users/username/Work/git/project-name

# Step 1: 認証確認
gh auth status

# Step 2: 以降の操作...
```

#### 悪い例（NG）

```bash
# ❌ ディレクトリ移動を省略
jj bookmark list
gh pr create --head feature --base main
```

**問題点:**
- ユーザーが間違ったディレクトリで実行するリスク
- コマンドが失敗する可能性が高い
- やり直しが必要になる

#### 良い例（OK）

```bash
# ✅ ディレクトリ移動を明示
# Step 0: jujutsu-practiceディレクトリに移動
cd /Users/arigatatsuya/Work/git/jujutsu-practice

# Step 1: ブックマーク確認
jj bookmark list

# Step 2: PR作成
gh pr create --head feature --b