karaage0703 dev-workflow
ソフトウェア開発タスクを、リポジトリ状態の確認から PR 作成・記録まで一貫して進めるためのスキル。
原則
- 先に状態を見る —
git fetch、git status、既存 PR の有無を確認してから作業する - 既存変更を壊さない — 自分が作っていない未コミット変更を勝手に戻さない
- 共有リポジトリは PR フロー — 公開・共有リポジトリでは小さな変更でもブランチを切る
- 検証を書く — PR 本文に何を確認したかを残す
- 節目を記録する — 長く続く作業は
memory/YYYYMMDD.mdやMEMORY.mdに状態を残す - 公開操作は確認する — push、PR作成、merge、release など公開リポジトリに影響する操作は、対象と操作内容を明示してユーザーのOKを取る
Step 1: 作業種別を決める
- 既存リポジトリの修正: このスキルで続行
- 小さな新規ツールやスクリプト: このスキルで続行
- 要件が曖昧な大規模新規開発: 先に要件・設計・タスクへ分解する
- 外部 API / SDK / フレームワークを使う実装: 実装前に最新ドキュメントを確認する
実装前に次の4点を短く固定する。
- ユーザーが解決したい問題
- 最初に触って確認できる最小のend-to-end経路
- 今回やらないこと
- ユーザーが成功と判断できる確認条件
将来向けの共通基盤や抽象化は、この最小経路に必要になるまで先行実装しない。
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 本文と報告に理由を書く。
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本文も更新する。追加要件が入った場合、変更前にもらったレビュー・マージ承認を新しい差分へ流用しない。
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を検索してから判断する
- 要件追加後も古い承認で進める: 差分と検証を更新し、必要な承認を取り直す