---
name: xs-dev-workflow
description: ソフトウェア開発タスクを進めるときの基本フロー。立ち上げ、ブランチ運用、実装、検証、PR作成、記録までを一気通貫で扱う。「実装して」「修正して」「PR作って」「コードを書く」「dev-workflow」で使用。
---

# dev-workflow

ソフトウェア開発タスクを、リポジトリ状態の確認から PR 作成・記録まで一貫して進めるためのスキル。

## 原則

1. **先に状態を見る** — `git fetch`、`git status`、既存 PR の有無を確認してから作業する
2. **既存変更を壊さない** — 自分が作っていない未コミット変更を勝手に戻さない
3. **共有リポジトリは PR フロー** — 公開・共有リポジトリでは小さな変更でもブランチを切る
4. **検証を書く** — PR 本文に何を確認したかを残す
5. **節目を記録する** — 長く続く作業は `memory/YYYYMMDD.md` や `MEMORY.md` に状態を残す
6. **公開操作は確認する** — push、PR作成、merge、release など公開リポジトリに影響する操作は、対象と操作内容を明示してユーザーのOKを取る

## Step 1: 作業種別を決める

- **既存リポジトリの修正**: このスキルで続行
- **小さな新規ツールやスクリプト**: このスキルで続行
- **要件が曖昧な大規模新規開発**: 先に要件・設計・タスクへ分解する
- **外部 API / SDK / フレームワークを使う実装**: 実装前に最新ドキュメントを確認する

実装前に次の4点を短く固定する。

1. ユーザーが解決したい問題
2. 最初に触って確認できる最小のend-to-end経路
3. 今回やらないこと
4. ユーザーが成功と判断できる確認条件

将来向けの共通基盤や抽象化は、この最小経路に必要になるまで先行実装しない。

## Step 2: リポジトリ状態を確認する

```bash
git fetch origin
git status --short --branch
git branch --show-current
```

見るポイント:
- いまいるブランチが作業対象と一致しているか
- 未コミット変更があるか
- その変更は自分のものか、既存のものか
- 既に関連 PR が開いていないか

既存の未コミット変更がある場合、自分の作業と関係するものだけ慎重に扱う。無関係な変更は触らない。

## Step 3: ブランチを切る

共有・公開リポジトリでは原則として専用ブランチを作る。

```bash
git pull --ff-only
git switch -c fix/<short-topic>
```

既に関連 PR が開いている場合:
- 小さく関連が強い変更: 既存 PR に乗せる
- 独立した変更: 別ブランチ・別 PR にする
- 判断に迷う場合: ユーザーに確認する

## Step 4: 実装する

既存の構成・命名・テスト方針に合わせる。新しい抽象化や依存は、実際に複雑さを減らす場合だけ追加する。

「機能がない」「新しく実装する」と判断する前に、コード、設定例、README、docs、testsを検索する。コードと文書に機能がありruntimeだけ失敗する場合は、実装不足ではなく設定・反映・運用の問題として調査する。

編集後は差分を確認する。

```bash
git diff
```

## Step 5: 検証する

変更内容に応じて最小限でも検証する。

例:
- ドキュメントのみ: `git diff --check`
- Python: `pytest`、対象スクリプトの実行
- Node.js: `npm test`、`npm run lint`、`npm run build`
- UI: ローカル起動と画面確認

実行できなかった検証があれば、PR 本文と報告に理由を書く。

- 初回利用・セットアップを変える場合は、既存の認証や事前データに依存しない隔離環境で、初期状態から目的を達成できることを確認する。本番設定を消して試さない。
- ローカルでは変更箇所のテスト・短い静的検査・実機確認を行い、全体の回帰はCIへ任せる。CIがない場合や失敗再現が必要な場合はローカルで補う。同じ成功済み検査を理由なく繰り返さない。
- 作業ディレクトリごとにlockfileに従って依存を導入する（例: `npm ci` / `uv sync --frozen`）。別checkoutの依存ディレクトリを共有して検証済みとしない。
- lint・test・buildは対象リポジトリで定義されたコマンドを使う。

## Step 6: コミットする

ステージングは対象ファイルを明示する。

```bash
git add <file1> <file2>
git diff --cached
git commit -m "<summary>"
```

`git add .` や `git add -A` は、無関係な変更を巻き込みやすいので避ける。

## Step 7: PR を作る

公開リポジトリで `git push` や `gh pr create` を行う前に、次のように対象操作を明示してユーザーのOKを取る。

```text
これから public repo <owner>/<repo> に以下を実行します。
- branch <branch> を push
- PR を作成

OK？
```

OKが出たら実行する。

```bash
git push -u origin <branch>
gh pr create --title "<タイトル>" --body "$(cat <<'EOF'
## 概要
- <変更点1>
- <変更点2>

## 検証
- [x] <実行した確認>
- [ ] <未確認の確認>
EOF
)"
```

PR 本文には以下を書く:
- 何を変えたか
- なぜ変えたか
- どう検証したか
- 未確認や残課題があるか

仕様、スコープ、検証結果が変わったら、その時点でPR本文も更新する。追加要件が入った場合、変更前にもらったレビュー・マージ承認を新しい差分へ流用しない。

## マージ・配備・再起動

マージ、稼働環境への配備、サービス再起動はそれぞれ別操作として、ユーザーが許可した範囲だけ実行する。まとめて明示許可された場合は再確認しない。

- マージ前: 対象PRの最新HEAD・検証結果・未解決指摘を確認する。
- 配備前: 稼働checkoutと反映対象、設定・依存関係を確認する。
- 再起動後: 実際のプロセス状態、反映された版、疎通を確認する。
- 報告例: 「PRはマージ済み。配備・再起動は未実施」。コード統合だけで本番反映済みとは報告しない。

## Step 8: 記録する

作業が長引く、別チャンネル・別セッションで引き継ぐ、PR を作った、方針転換した、完了した。こうした節目では記録する。

記録先:
- `memory/YYYYMMDD.md`: その日の作業ログ
- `MEMORY.md`: 継続中プロジェクトや長期的に残すべき情報
- `notes/`: 調査結果や設計メモ

記録例:

```markdown
### <repo>: <作業名>
- PR: <URL>
- 内容: <1〜3行>
- 検証: <実行したコマンドや確認>
- 次: <残っていること>
```

## よくある事故とガード

- **古い main からブランチを切る**: `git fetch origin` を省略しない
- **無関係な変更をコミットする**: `git add .` を避け、`git diff --cached` を必ず見る
- **PR 本文が古いまま残る**: 仕様変更や検証追加のたびに本文を更新する
- **共有ファイルを上書きする**: `memory/`、`MEMORY.md`、`AGENTS.md` のような共有ファイルは編集直前に再読する
- **検証できていないのに完了扱いにする**: 未検証なら未検証と書く
- **既存機能を未実装扱いする**: コード、設定例、docs、testsを検索してから判断する
- **要件追加後も古い承認で進める**: 差分と検証を更新し、必要な承認を取り直す