/xs-dev-workflow

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: リポジトリ状態を確認する

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

見るポイント:

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

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

Step 3: ブランチを切る

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

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

既に関連 PR が開いている場合:

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

Step 4: 実装する

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

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

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

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: コミットする

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

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を取る。

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

OK？

OKが出たら実行する。

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/`: 調査結果や設計メモ

記録例:

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

よくある事故とガード

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