karaage0703/ai-assistant-workspace/xs-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を検索してから判断する
• 要件追加後も古い承認で進める: 差分と検証を更新し、必要な承認を取り直す