diff --git a/.claude/commands/sync-template.md b/.claude/commands/sync-template.md index 59733a8..0372706 100644 --- a/.claude/commands/sync-template.md +++ b/.claude/commands/sync-template.md @@ -12,6 +12,18 @@ テンプレート URL: `https://github.com/rintoHasegawa/programming-template.git` +## マージ必須ファイル (Merge-required Files) + +以下のファイルは「プロジェクト固有の内容 + テンプレートの共通ルール」のハイブリッドのため,**上書きせずマージする**.コピー処理(ステップ 5.3)に入る前に対象ファイルかを判定し,該当する場合はステップ 5.4 のマージ手順に分岐させる. + +| ファイル | 理由 | マージ方針 | +| --- | --- | --- | +| `.gitignore` | フレームワーク固有ルール(Flutter/Node 等)を保持する必要がある | テンプレート側の実効行で既存に含まれないもののみを追記.既存行は触らない | +| `CLAUDE.md` | プロジェクト名・開発進捗・固有規約を保持する必要がある | テンプレートで変更された共通セクション(必須ルール,エージェントチーム,ドキュメント構成等)のみを Edit で更新.プロジェクト固有セクションは触らない | +| `.gitattributes` | プロジェクトによって設定が異なる可能性がある | 差分を表示し,ユーザーに「上書き / マージ / スキップ」を問う | + +マージ処理の対象は **既存ファイルが存在する場合のみ**.初回同期(`.claude/template-sync-sha` がない状態)では全ファイルが A 扱いとなるが,これらのファイルはフレームワーク初期化(`flutter create` / `npm init` 等)や `/init` で既にプロジェクトに存在するのが通常なので,そのままマージ処理に入る.既存ファイルがない稀なケースに限り通常の `cp` で配置する. + ## ステップ 1: 事前確認 `git status` でワーキングツリーがクリーンか確認する. @@ -64,7 +76,7 @@ ## ステップ 4: 変更一覧をユーザーに提示 -取り込み対象のファイル一覧を種別ごとに整理してユーザーに提示する: +取り込み対象のファイル一覧を種別ごとに整理してユーザーに提示する.マージ必須ファイル(`.gitignore`, `CLAUDE.md`, `.gitattributes`)に変更がある場合は,**ユーザーが取り込み前に影響範囲を把握できるよう差分サマリーを先出しする**: 「**テンプレートに以下の変更があります:** @@ -73,54 +85,154 @@ - 削除 (D): {ファイル一覧} - リネーム (R): {旧名 → 新名} +**⚠ マージ必須ファイル(上書きせず差分マージします):** + +- `.gitignore`(既存 {N} 行 / テンプレート {M} 行.既存の固有ルールを保持し,テンプレート側で追加されている {K} 行を追記) +- `CLAUDE.md`(既存にプロジェクト固有セクションが {L} 行.テンプレート更新セクションのみマージ) +- `.gitattributes`(差分 {D} 行.処理方針をユーザーに確認) + 取り込みを開始します.」 +差分サマリーは以下で取得する(該当ファイルがマージ対象かつ既存ファイルがある場合のみ出力): + +```bash +# 既存ファイル行数 +wc -l .gitignore CLAUDE.md .gitattributes 2>/dev/null + +# テンプレート側の実効行数(.gitignore) +grep -vE '^\s*(#|$)' "$TEMP_DIR/.gitignore" | wc -l + +# 既存ファイルとテンプレート最新版の差分プレビュー +diff -u .gitignore "$TEMP_DIR/.gitignore" | head -30 +diff -u CLAUDE.md "$TEMP_DIR/CLAUDE.md" | head -50 +diff -u .gitattributes "$TEMP_DIR/.gitattributes" | head -30 +``` + ## ステップ 5: ブランチ作成とファイル反映 -1. `git checkout -b chore/sync-template` でブランチを作成する - - 既に同名のブランチが存在する場合は削除してから作り直す +### 5.1 ブランチ作成 -2. 追加・変更・リネーム先を反映する: +`git checkout -b chore/sync-template` でブランチを作成する.既に同名のブランチが存在する場合は削除してから作り直す. +### 5.2 マージ必須ファイル判定ヘルパー + +以降の処理で利用する判定関数を定義する: + +```bash +MERGE_FILES=(".gitignore" "CLAUDE.md" ".gitattributes") + +is_merge_file() { + local t="$1" + for f in "${MERGE_FILES[@]}"; do + [ "$f" = "$t" ] && return 0 + done + return 1 +} +``` + +### 5.3 通常コピー対象の反映(マージ必須ファイル以外) + +マージ必須ファイルは後段(5.4)で個別処理するため,このループではスキップする.既存ファイルがない場合は通常どおり `cp` で配置する: + +```bash +echo "$CHANGED_ENTRIES" | while IFS=$'\t' read -r status file newfile; do + [ -z "$status" ] && continue + case "$status" in + A|M) + # マージ必須ファイルで既存ファイルがある場合は 5.4 で処理 + if is_merge_file "$file" && [ -f "$file" ]; then + continue + fi + mkdir -p "$(dirname "$file")" + cp "$TEMP_DIR/$file" "$file" + ;; + R*) + # file=旧パス, newfile=新パス + if is_merge_file "$newfile" && [ -f "$newfile" ]; then + continue + fi + mkdir -p "$(dirname "$newfile")" + cp "$TEMP_DIR/$newfile" "$newfile" + ;; + esac +done +``` + +### 5.4 マージ必須ファイルの個別処理 + +`$CHANGED_ENTRIES` に A/M/R* で含まれ,かつ既存ファイルが存在するマージ必須ファイルについて,以下の手順で処理する. + +**`.gitignore` のマージ手順** + +1. 既存 `.gitignore` とテンプレート `$TEMP_DIR/.gitignore` を読む +2. テンプレート側の**実効行**(コメント `#` 行・空行を除く)を抽出する: ```bash - echo "$CHANGED_ENTRIES" | while IFS=$'\t' read -r status file newfile; do - [ -z "$status" ] && continue - case "$status" in - A|M) - mkdir -p "$(dirname "$file")" - cp "$TEMP_DIR/$file" "$file" - ;; - R*) - # file=旧パス, newfile=新パス - mkdir -p "$(dirname "$newfile")" - cp "$TEMP_DIR/$newfile" "$newfile" - ;; - esac - done + grep -vE '^\s*(#|$)' "$TEMP_DIR/.gitignore" ``` +3. 抽出した各行について,既存ファイルに完全一致で含まれていないものだけを収集する +4. 収集した行がある場合,既存ファイル末尾に以下のマーカー付きブロックで追記する: + ``` + + # --- from template (sync-template) --- + {追加行} + ``` + - 既存ファイル末尾に同じマーカーが既にある場合は,マーカー以降に追記して重複マーカーを作らない +5. `git diff .gitignore` で結果を表示しユーザーに確認する -3. 削除候補(D およびリネーム元)を抽出する: +**`CLAUDE.md` のマージ手順** +同期担当エージェント(= あなた)が Read と Edit ツールを使ってセクション単位でマージする: + +1. 既存 `CLAUDE.md` とテンプレート版 `$TEMP_DIR/CLAUDE.md` を Read する +2. テンプレート側の変更箇所を特定する(初回同期は LAST_SHA がないためテンプレート全体を「更新候補」として扱う): ```bash - DELETIONS=$(echo "$CHANGED_ENTRIES" | awk -F'\t' '$1 == "D" {print $2} $1 ~ /^R/ {print $2}') + if [ -n "$LAST_SHA" ]; then + git -C "$TEMP_DIR" show "$LAST_SHA:CLAUDE.md" 2>/dev/null > /tmp/claude_md_old || true + diff -u /tmp/claude_md_old "$TEMP_DIR/CLAUDE.md" + fi ``` +3. セクションを以下の基準で分類する: + - **共通セクション(テンプレート管理,更新対象)**: 「必須ルール」「エージェントチーム」「Git 運用」「ドキュメント」節など,テンプレートに由来する節 + - **プロジェクト固有セクション(保持対象)**: 「プロジェクト名」「開発進捗」や,プロジェクトが追加した固有規約の節 +4. テンプレート側で変更があった共通セクションのみを Edit で既存ファイルに反映する.プロジェクト固有セクションは一切触らない +5. `git diff CLAUDE.md` で結果を表示しユーザーに確認する -4. `$DELETIONS` が空でない場合,ユーザーに確認を求める: +**`.gitattributes` のマージ手順** - 「**以下のファイルはテンプレートから削除されています:** - - {削除候補一覧} - - プロジェクトからも削除してよいですか?(残したいファイルがあれば指定してください)」 - - ユーザー確認後,対象ファイルを `rm` で削除する.プロジェクトが独自に残したいファイルは削除対象から除外する. - -5. 同期済み SHA を記録し,一時ディレクトリを削除する: - +1. 既存ファイルとテンプレート版の差分を表示する: ```bash - echo "$NEW_SHA" > .claude/template-sync-sha - rm -rf "$TEMP_DIR" + diff -u .gitattributes "$TEMP_DIR/.gitattributes" ``` +2. ユーザーに以下のいずれかを選ばせる: + - **上書き**: テンプレート版で既存を置換 + - **マージ**: 両者のルールを統合(具体的な統合内容は対話で決定) + - **スキップ**: 既存ファイルを維持 +3. 選択に応じて処理する + +### 5.5 削除候補の確認 + +削除候補(D およびリネーム元)を抽出する: + +```bash +DELETIONS=$(echo "$CHANGED_ENTRIES" | awk -F'\t' '$1 == "D" {print $2} $1 ~ /^R/ {print $2}') +``` + +`$DELETIONS` が空でない場合,ユーザーに確認を求める: + +「**以下のファイルはテンプレートから削除されています:** + +{削除候補一覧} + +プロジェクトからも削除してよいですか?(残したいファイルがあれば指定してください)」 + +ユーザー確認後,対象ファイルを `rm` で削除する.プロジェクトが独自に残したいファイルは削除対象から除外する. + +### 5.6 同期済み SHA の記録とクリーンアップ + +```bash +echo "$NEW_SHA" > .claude/template-sync-sha +rm -rf "$TEMP_DIR" +``` ## ステップ 6: 変更内容の分析 @@ -160,5 +272,7 @@ - テンプレートリポジトリへの push は行わない - コード修正はユーザーの確認なしに実行しない -- ファイルコピーによりプロジェクト固有の変更が上書きされる場合は,`git diff` で確認してユーザーに報告する +- マージ必須ファイル(`.gitignore`, `CLAUDE.md`, `.gitattributes`)は必ずステップ 5.4 の手順でマージする.盲目的な `cp` で上書きしない(フレームワーク固有の除外ルールやプロジェクト固有セクションが失われる) +- 通常コピー対象でもプロジェクト固有の変更が上書きされうる場合は,`git diff` で確認してユーザーに報告する +- テンプレートが管理するのは `.claude/` 配下のうち `agents/`,`commands/`,`hooks/`,`settings.json`,`template-sync-sha` のみ.`.claude/plans/` や `.claude/commit-context.md` 等のプロジェクト固有ファイルはテンプレートに含まれないため同期対象外 - `chore/sync-template` ブランチは他の作業ブランチと混ぜず,作成後は速やかにマージすること.複数の作業ブランチで `/sync-template` を実行すると `.claude/template-sync-sha` がコンフリクトする.コンフリクト時は新しい(HEAD 側の)SHA を採用すること. diff --git a/.claude/template-sync-sha b/.claude/template-sync-sha index 8c20381..49722ad 100644 --- a/.claude/template-sync-sha +++ b/.claude/template-sync-sha @@ -1 +1 @@ -21c46e72e74f77a7dee7488d803b08e33b3c95bd +edf620587f1798319fa8412e55e7b99bf17528a4 diff --git a/.gitattributes b/.gitattributes new file mode 100644 index 0000000..6313b56 --- /dev/null +++ b/.gitattributes @@ -0,0 +1 @@ +* text=auto eol=lf diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..c2c82e5 --- /dev/null +++ b/.gitignore @@ -0,0 +1,13 @@ +# /implement が /commit に渡すコンテキストファイル +.claude/commit-context.md + +# サブプロジェクト(一旦トラッキング対象外) +MiniTIAS/ +MiniTias-Evaluation/ + +# -- プロジェクト立ち上げ時に有効化する(GUIDE_04 参照) -- +# .env +# .env.* +# node_modules/ +# build/ +# dist/ diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..82fce2d --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,66 @@ +# プロジェクト名 + + + +## 開発進捗 + +現在の進捗: GUIDE_01 に従いプロジェクト立ち上げ中 +※ ステップ完了時にここを更新すること. + +## 必須ルール(コード実装時) + + + +### Git 運用(GUIDE_04 準拠) + +- ブランチ名・コミットメッセージの書式は GUIDE_04 に従う +- コミットは `/commit` を使用する(push・PR 作成は `/commit push`) + +### エージェントチーム(GUIDE_05 準拠) + +- 実装は `/implement <タスク>` で開始する(コーディング → テスト → リファクタリング → ドキュメント更新) +- Phase 1 後に人間が動作確認,Phase 2 でテスト失敗時のみ方針判断 +- Phase 2 成功後は Phase 3 → Phase 4 まで自動で進む(Phase 4 で更新がある場合のみ確認) +- テスト・リファクタリングをスキップしない + +### 手動確認が必要な作業(自分で完了させないこと) + +以下は実装完了後にユーザーへ報告し,確認・実施を依頼すること. + +- 外部サービスの設定(コンソール操作,セキュリティルール変更等) +- 実機・ブラウザでの動作確認 +- ストアへのアップロード・リリース作業 + +## ドキュメント + +設計・規約に関する情報は docs/ にある. +コードを書く前に関連するファイルを読むこと. + +### 01_GUIDE(規約・ルール) + +- プロジェクト立ち上げフロー: docs/01_GUIDE/GUIDE_01_プロジェクト立ち上げフロー.md +- ドキュメント作成規約: docs/01_GUIDE/GUIDE_02_ドキュメント作成ガイド.md +- ファイル命名規則: docs/01_GUIDE/GUIDE_03_ファイル命名規則.md +- Git 運用ルール: docs/01_GUIDE/GUIDE_04_Git運用ルール.md +- エージェント運用ルール: docs/01_GUIDE/GUIDE_05_エージェント運用ルール.md +- ※ コーディング規約,テスト方針等はプロジェクト立ち上げ時に作成する(GUIDE_01 参照) + +### 02_ENV(環境) + + + +### 03_PLAN(計画) + + + +### 04_SPEC(仕様・設計) + + + +### 05_TECH(技術設計) + + + +### 06_TEST(テスト) + + diff --git "a/docs/01_GUIDE/GUIDE_01_\343\203\227\343\203\255\343\202\270\343\202\247\343\202\257\343\203\210\347\253\213\343\201\241\344\270\212\343\201\222\343\203\225\343\203\255\343\203\274.md" "b/docs/01_GUIDE/GUIDE_01_\343\203\227\343\203\255\343\202\270\343\202\247\343\202\257\343\203\210\347\253\213\343\201\241\344\270\212\343\201\222\343\203\225\343\203\255\343\203\274.md" new file mode 100644 index 0000000..b3b8893 --- /dev/null +++ "b/docs/01_GUIDE/GUIDE_01_\343\203\227\343\203\255\343\202\270\343\202\247\343\202\257\343\203\210\347\253\213\343\201\241\344\270\212\343\201\222\343\203\225\343\203\255\343\203\274.md" @@ -0,0 +1,128 @@ +# プロジェクト立ち上げフロー (Project Setup Flow) + +新規プロジェクトを AI と協働で立ち上げる際の手順を定義する. +各フェーズを順番に進め,成果物を確定させてから次のフェーズに移ること. + +## フェーズ一覧 (Phase Overview) + +| フェーズ | やること | 成果物 | +| -------- | ---------------------------------------------- | ---------------------------------------------------------- | +| 方針決定 | プロジェクトの目的・スコープを決める | `PLAN_01_要件定義書.md` | +| 技術選定 | 言語・フレームワーク・インフラを決める | `ENV_01_技術スタック.md` | +| 環境構築 | 開発環境のセットアップ手順を整備する | `ENV_02_環境構築手順.md`,`ENV_03_管理者用環境構築手順.md` | +| 仕様設計 | アーキテクチャ・データモデル・画面設計を決める | `SPEC_01_*.md` | +| 規約整備 | 技術スタックに応じたコーディング規約を作る | `GUIDE_*_*.md` | +| 開発計画 | ステップを分割し,開発順序を決める | `PLAN_02_開発ステップ.md` | +| 実装開始 | 開発計画に沿って実装を進める | ソースコード | + +## 方針決定 (Direction) + +プロジェクトの全体像を明確にする. + +- **人間が決めること**: プロジェクトの目的,対象ユーザー,スコープ(やること・やらないこと) +- **AI に依頼できること**: 要件の整理・構造化,類似プロジェクトの調査,要件定義書のドラフト作成 +- **成果物**: `PLAN_01_要件定義書.md` + +## 技術選定 (Tech Stack) + +要件に基づいて技術スタックを決定する. + +- **人間が決めること**: 最終的な技術選定の判断,チームのスキルセットとの適合性 +- **AI に依頼できること**: 要件に適した技術の候補提案,各候補のメリット・デメリット比較 +- **成果物**: `ENV_01_技術スタック.md` + +## 環境構築 (Environment Setup) + +開発環境を構築し,手順をドキュメント化する.初回のみの管理者作業と,メンバーが繰り返し行う構築手順を分けて整備する. + +- **前提条件**: 以下のツールは全プロジェクト共通で導入する. + - `git` — バージョン管理([GUIDE_04](GUIDE_04_Git運用ルール.md) で運用ルールを定義) + - `gh` — GitHub CLI(PR 作成・マージ等に使用) +- **テンプレートからのプロジェクト作成**: + 以下の手順でテンプレートをコピーし,履歴を引き継がない新規リポジトリとして初期化する. + + ```bash + # 1. プロジェクトディレクトリを作成して移動 + mkdir + cd + + # 2. カレントディレクトリにテンプレートをクローン(末尾の . に注意) + git clone https://github.com/rintoHasegawa/programming-template.git . + + # 3. 現在のテンプレート SHA を記録(以降の /sync-template で差分同期するため) + git rev-parse HEAD > .claude/template-sync-sha + + # 4. テンプレートの git 履歴を削除し,新しいリポジトリとして初期化 + rm -rf .git + git init -b main + ``` + + 以降,テンプレートの更新を取り込むときは `/sync-template` を実行する. +- **基本方針**: 環境の再現性を重視し,手順書だけに頼らず構築を自動化・コード化できる方法を優先する(例: Docker,Dev Containers,Windows Sandbox,IaC ツール等). +- **人間が決めること**: 開発マシンの選定,クラウドサービスのアカウント作成,環境構築方法の選択 +- **AI に依頼できること**: 環境構築手順書の作成,設定ファイルの生成,`.gitignore` の作成,Dockerfile や devcontainer.json 等の構築用ファイルの作成 +- **成果物**: + - `ENV_02_環境構築手順.md` — メンバーの参加時や環境の再構築時に使う手順 + - `ENV_03_管理者用環境構築手順.md` — プロジェクト作成時に一度だけ行う初期設定(リポジトリ作成,外部サービスの設定等) + +## 仕様設計 (Specification) + +アプリケーションの設計を行う. + +- **人間が決めること**: ユーザー体験の方針,ビジネスロジックの最終判断 +- **AI に依頼できること**: アーキテクチャ設計のドラフト,データモデル定義,画面遷移図の整理 +- **成果物**: `SPEC_01_*.md`(プロジェクトの規模に応じて複数ファイルに分割) + +## 規約整備 (Coding Standards) + +技術スタックに応じたコーディング規約やプロジェクト固有のガイドを作成する. +汎用ガイド(GUIDE_01〜05)は本テンプレートに含まれている.ここではプロジェクト固有の規約を追加する. + +- **基本方針**: 言語・フレームワークの公式ガイドラインや広く採用されている標準規約に則る(例: Effective Dart,PEP 8,Google Style Guide 等).プロジェクト固有のルールは標準と異なる部分のみ定義する. +- **人間が決めること**: 標準規約でカバーされない判断(アーキテクチャパターンの選択等) +- **AI に依頼できること**: 標準規約を踏まえた規約のドラフト作成,参照元ガイドラインの調査 +- **作成すべきガイド**(推奨番号は GUIDE_03 に準拠): + - `GUIDE_06` コーディング規約 — 命名規則,フォーマット,import 順序,型の使い方,コメントの書き方,コード内ドキュメントの規則 + - `GUIDE_07` ディレクトリ構造規則 — プロジェクトのディレクトリ構成とファイル配置ルール + - `GUIDE_08` テスト方針 — テストの種類,粒度,実行タイミング,カバレッジ基準,モック方針,テストファイルの配置規則 + - `GUIDE_09` エラーハンドリング方針 — エラーの分類,処理方法,ログ出力の方針 + - ※ リファクタリング方針は言語に依存しないため,`.claude/agents/refactorer.md` の判断基準を共通ルールとして使用する + - ※ 機能実装完了フローは GUIDE_05 と `/implement` で定義済みのため,別途作成しない + +## 開発計画 (Development Plan) + +実装の順序とステップを決定する. + +- **人間が決めること**: 優先度,リリース計画,マイルストーン +- **AI に依頼できること**: 仕様を元にしたステップ分割の提案,依存関係の整理 +- **成果物**: `PLAN_02_開発ステップ.md` + +## 実装開始 (Implementation) + +開発計画に沿って AI と協働で実装を進める. + +- 各ステップの完了時に [GUIDE_02_ドキュメント作成ガイド](GUIDE_02_ドキュメント作成ガイド.md) と [GUIDE_04_Git運用ルール](GUIDE_04_Git運用ルール.md) に従ってコミット・PR を作成する. +- 仕様変更が発生した場合は,先にドキュメントを更新してから実装に反映する. + +## CLAUDE.md の管理 (CLAUDE.md Management) + +`CLAUDE.md` は AI が会話開始時に最初に読むファイルであり,プロジェクトの引継ぎ情報を一元管理する. +AI は毎回新しい会話で始まるため,このファイルが唯一の継続的な文脈となる. + +### 記載すべき内容 + +- **プロジェクト概要**: プロジェクト名,目的,技術スタックの要約 +- **開発進捗**: 現在のステップ,次にやること +- **必須ルール**: AI が実装時に必ず守るべきルール(コーディング規約,コミット前チェック等の要点) +- **ドキュメント一覧**: docs/ 内のファイルへの参照パス + +### 更新タイミング + +- ステップの完了時に開発進捗を更新する +- ドキュメントの追加・削除・リネーム時に参照パスを更新する +- 必須ルールに変更があった場合に反映する + +### 運用上の注意 + +- CLAUDE.md は AI が毎回読み込むため,簡潔に保つ.詳細は docs/ のドキュメントに委ね,CLAUDE.md には要点と参照先のみ記載する. +- プロジェクト固有のルールが増えたら,docs/ に独立ファイルとして切り出し,CLAUDE.md からはリンクで参照する. diff --git "a/docs/01_GUIDE/GUIDE_02_\343\203\211\343\202\255\343\203\245\343\203\241\343\203\263\343\203\210\344\275\234\346\210\220\343\202\254\343\202\244\343\203\211.md" "b/docs/01_GUIDE/GUIDE_02_\343\203\211\343\202\255\343\203\245\343\203\241\343\203\263\343\203\210\344\275\234\346\210\220\343\202\254\343\202\244\343\203\211.md" new file mode 100644 index 0000000..ed91906 --- /dev/null +++ "b/docs/01_GUIDE/GUIDE_02_\343\203\211\343\202\255\343\203\245\343\203\241\343\203\263\343\203\210\344\275\234\346\210\220\343\202\254\343\202\244\343\203\211.md" @@ -0,0 +1,114 @@ +# ドキュメント作成ガイドライン (Documentation Style Guide) + +本ガイドはプロジェクト内のマークダウンドキュメントの書式を統一するためのルールを定める. +基本方針として [Google Markdown Style Guide](https://google.github.io/styleguide/docguide/style.html) および [markdownlint](https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md) のルールに準拠し,本ガイドで上書きする項目のみ以下に記載する. + +## 基本フォーマット (Basic Format) + +- 文字コード: UTF-8 +- 改行コード: LF(推奨)または CRLF +- ファイル拡張子: `.md` +- ファイル末尾: 空行を 1 行入れて終了する(MD047) + +## 句読点・約物 (Punctuation) + +- 句読点: 「,」(全角カンマ)と「.」(全角ピリオド)を使用する. + - 「、」「。」は使用しない. +- コロン: 半角コロン+半角スペース「: 」を使用する. + - NG: 全角コロン「:」,スペースなし「:」 +- 括弧: 原則として半角 `( )` を使用する.強調や補足には全角 `( )` や `「 」` も許容する. +- 注釈: 補足には「※」(全角米印)+半角スペースを使用する. + - 例: ※ shared は client/server 両方から import して使用する. + +## 見出し (Headings) + +ATX スタイル(`#`)を使用する.Setext スタイル(`===` / `---` の下線)は使用しない. + +- `#` の後に半角スペースを 1 つ入れる(MD018) +- 見出しの前後に空行を 1 行入れる(MD022) +- 見出しレベルは飛ばさない(MD001) + - NG: `#` の直下に `###` +- ドキュメント内の `#`(H1)は 1 つだけにする(MD025) +- 見出しには番号を付けない.マークダウンの見出し構造で階層を表現する. +- 見出しの書式: `タイトル (English Title)` + - 例: `## 基本設計 (Basic Design)` + +### 見出しレベルの対応表 + +| レベル | 記法 | 用途 | +| --- | --- | --- | +| H1 | `#` | ドキュメントタイトル(ファイルに 1 つ) | +| H2 | `##` | 大見出し(セクション) | +| H3 | `###` | 中見出し(サブセクション) | +| H4 | `####` | 小見出し(トピック) | + +## リスト (Lists) + +- 箇条書きには `- `(半角ハイフン+半角スペース)を使用する(MD004) + - `*` `+` `・` は使用しない. +- ネストは 2 スペースでインデントする(MD007) +- 順序付きリストは `1.` の連番で記述する. +- リストの前後に空行を 1 行入れる(MD032) + +## 強調 (Emphasis) + +- 太字: `**テキスト**` を使用する.`__テキスト__` は使用しない(MD050) +- 斜体: `*テキスト*` を使用する.`_テキスト_` は使用しない(MD049) +- 太字斜体: `***テキスト***` を使用する. + +## コードブロック・インラインコード (Code) + +- コードブロックにはフェンス(` ``` `)を使用し,言語名を明記する(MD040) + + ````markdown + ```dart + final name = 'DxNavi'; + ``` + ```` + +- インラインコードにはバッククォート `` ` `` を使用する. + - 例: `build_runner` コマンドを実行する. +- コマンド例にはシェル言語を指定する. + + ````markdown + ```bash + dart run build_runner build --delete-conflicting-outputs + ``` + ```` + +## リンク・画像 (Links & Images) + +- リンク: `[テキスト](URL)` 形式を使用する. +- 画像: `![代替テキスト](パス)` 形式を使用し,代替テキストを必ず記述する(MD045) +- プロジェクト内リンクは相対パスを使用する. + +## テーブル (Tables) + +- ヘッダー行とセパレータ行を必ず含める. +- セル内は簡潔に記述し,長い場合はリンクや脚注で補足する. + +```markdown +| 項目 | 説明 | +| --- | --- | +| 名前 | 値 | +``` + +## 空行・余白 (Spacing) + +- 連続する空行は最大 1 行までとする(MD012) +- 見出し・リスト・コードブロックの前後に空行を 1 行入れる(MD022, MD031, MD032) +- 行末の不要な空白は削除する(MD009) + +## その他 (Miscellaneous) + +- HTML タグは原則使用しない.マークダウン記法で表現できない場合のみ許容する. +- 1 行の長さに厳密な上限は設けないが,可読性のために適度に改行する. +- ディレクトリ構造の表現にはコードブロック内でツリー記号(`├──`,`│`,`└──`)を使用する. + +```text +project/ +├── lib/ +│ ├── core/ +│ └── features/ +└── test/ +``` diff --git "a/docs/01_GUIDE/GUIDE_03_\343\203\225\343\202\241\343\202\244\343\203\253\345\221\275\345\220\215\350\246\217\345\211\207.md" "b/docs/01_GUIDE/GUIDE_03_\343\203\225\343\202\241\343\202\244\343\203\253\345\221\275\345\220\215\350\246\217\345\211\207.md" new file mode 100644 index 0000000..f9d43d2 --- /dev/null +++ "b/docs/01_GUIDE/GUIDE_03_\343\203\225\343\202\241\343\202\244\343\203\253\345\221\275\345\220\215\350\246\217\345\211\207.md" @@ -0,0 +1,31 @@ +# ドキュメント管理・ファイル命名規則 (File Naming Conventions) + +## 命名の基本方針 (Basic Policy) + +プロジェクトの規模拡大に伴うファイルの散乱を防ぎ,開発メンバーおよび AI がファイルの内容・文脈を即座に特定できるようにするため,以下の規則を適用する. + +### 基本フォーマット + +`[カテゴリ]_[連番]_[ファイル名].md` + +- 区切り文字: アンダースコア `_` を使用する. +- 連番: 01 から始まる 2 桁の数字とする. +- 拡張子: マークダウン `.md` とする. + +## カテゴリ定義 (Category Definitions) + +ファイル名の先頭に付与するプレフィックス(接頭辞)定義. + +| カテゴリ | ディレクトリ | 内容 | 対象例 | +| --- | --- | --- | --- | +| `GUIDE_` | `01_GUIDE/` | ルール,規約,運用フロー | スタイルガイド,命名規則,Git 運用ルール | +| `ENV_` | `02_ENV/` | 開発環境,プロジェクトの土台 | 環境構築手順,技術スタック一覧,パッケージ構成図 | +| `PLAN_` | `03_PLAN/` | 進行計画,スケジュール,要件定義 | WBS,ロードマップ,要件定義書,タスク一覧 | +| `SPEC_` | `04_SPEC/` | ユーザーから見える仕様 | 企画書,画面遷移図,パラメータ設定 | +| `TECH_` | `05_TECH/` | エンジニア向けの技術設計 | 通信プロトコル仕様,データベース設計,クラス設計 | +| `TEST_` | `06_TEST/` | テスト計画,品質保証 | 単体テスト仕様書,シナリオテスト計画,品質基準 | + +## 運用ルール (Operational Rules) + +- 1 ファイル 1 テーマ: ファイルサイズが肥大化しすぎないよう,トピックごとにファイルを分割することを推奨する.これにより,AI へのコンテキスト入力精度が向上する. +- スタイルの継承: 新規作成するファイルも,必ず [GUIDE_02_ドキュメント作成ガイド](GUIDE_02_ドキュメント作成ガイド.md) に記載された書式に従うこと. diff --git "a/docs/01_GUIDE/GUIDE_04_Git\351\201\213\347\224\250\343\203\253\343\203\274\343\203\253.md" "b/docs/01_GUIDE/GUIDE_04_Git\351\201\213\347\224\250\343\203\253\343\203\274\343\203\253.md" new file mode 100644 index 0000000..3b79351 --- /dev/null +++ "b/docs/01_GUIDE/GUIDE_04_Git\351\201\213\347\224\250\343\203\253\343\203\274\343\203\253.md" @@ -0,0 +1,181 @@ +# Git 運用ルール (Git Operation Rules) + +## 基本方針 (Basic Policy) + +チーム開発におけるコードの整合性を保ち,手戻りを防ぐために以下の運用フローを徹底する. + +- **メインブランチ (main)**: + - 本番環境または常に動作可能な状態を維持するブランチ. + - 直接のコミット(直プッシュ)は禁止する.必ずプルリクエスト(PR)経由でマージする. +- **作業ブランチ (Feature Branch)**: + - 機能追加やバグ修正ごとに `main` から派生させて作成する. + - 作業完了後,`main` へマージし,原則として削除する. +- **`.gitignore`**: + - リポジトリ作成時に必ず整備する. + - ビルド成果物,依存パッケージ(`node_modules/` 等),環境変数ファイル(`.env` 等)は必ず除外する. + - `git add .` を安全に使うための前提条件であるため,メンバー追加時にも確認する. + +## ブランチ命名規則 (Branch Naming) + +### プレフィックス (Prefix) + +作業の種類を一目で判別するために,以下のプレフィックスを使用する. + +| プレフィックス | 用途 | +| --- | --- | +| `feature/` | 新機能の実装,仕様変更 | +| `fix/` | バグ修正 | +| `refactor/` | コードの整理(挙動は変えない) | +| `docs/` | ドキュメントの追記・修正 | +| `chore/` | ビルド設定やツール導入など,雑多な作業 | + +### 書式 (Format) + +- 書式: `[プレフィックス][概要]` +- 区切り: スラッシュ `/` を使用する.概要内の単語区切りはハイフン `-` を使用する. +- 概要: 作業内容を端的に表す英単語 2〜4 語程度(小文字)とする. +- 例: + - `feature/player-jump` + - `fix/collision-bug` + - `docs/guide-update` + +## 開発フロー (Development Workflow) + +作業を開始してからマージされるまでの手順. + +### ローカルの最新化 + +作業開始前は必ず `main` ブランチに切り替え,リモートの最新状態を取り込む. + +```bash +git checkout main +git pull origin main +``` + +### 作業ブランチの作成 + +最新の `main` から新しいブランチを作成して移動する. + +```bash +git checkout -b feature/new-function +``` + +### 実装とコミット + +- 作業単位(意味のあるまとまり)ごとにコミットする. +- 巨大なコミットは避け,レビューしやすい粒度を心がける. +- AI によるコミットメッセージの生成機能を利用してもよい.ただし,生成されたメッセージは必ず「コミットメッセージ」セクションの書式ルールに合わせて修正すること. + +```bash +git add . +git commit -m "[add] 新機能を実装" +``` + +### リモートへのプッシュ + +作業ブランチをリモートリポジトリへ送信する. + +```bash +git push origin feature/new-function +``` + +### プルリクエスト (PR) の作成 + +GitHub CLI (`gh`) を使用して PR を作成する. + +```bash +gh pr create --title "[add] 新機能を実装" --body "概要" +``` + +- `--title` はコミットメッセージと同じ書式(`[タグ] 内容`)とする. +- 必要に応じて `--reviewer` でレビュワーを指定する. + +### レビューと修正の対応 + +- レビュワーのコメントを確認し,修正が必要な場合はローカルで修正・コミット・プッシュを繰り返す. +- 全ての指摘に対応し,レビュワーから Approve をもらう. + +### マージの実行 + +- マージ方式は「Create a merge commit」を使用する(作業ブランチの全コミット履歴が `main` に残る). + - 「Squash and merge」「Rebase and merge」は使用しない. + +```bash +gh pr merge --merge --delete-branch +``` + +### ローカル環境のクリーンアップ + +マージ完了後はローカル環境も最新状態に戻し,古いブランチを削除する. + +```bash +git checkout main +git pull origin main +git branch -d feature/new-function +``` + +## コミットメッセージ (Commit Messages) + +### 書式 + +- 書式: `[タグ] 内容` +- 言語: 日本語 +- 句読点: 末尾に句点は不要 + +### タグ一覧 + +| タグ | 用途 | +| --- | --- | +| `[add]` | ファイルや機能の追加 | +| `[update]` | 機能やデータの更新・修正 | +| `[fix]` | バグ修正 | +| `[remove]` | 削除 | +| `[clean]` | 整理,リファクタリング | + +## トラブルシューティング (Troubleshooting) + +### コンフリクトが発生した場合 + +他メンバーの変更と競合した場合の対処手順. + +**main の取り込み** + +作業ブランチに `main` の最新内容をリベースして競合箇所を洗い出す.`merge` ではなく `rebase` を使うことで,履歴が線形に保たれレビューしやすくなる. + +```bash +git checkout main +git pull origin main +git checkout feature/new-function +git rebase main +``` + +**競合の解消** + +エディタ上で `<<<<<<<`,`=======`,`>>>>>>>` で囲まれた箇所を手動で修正する.修正後,以下のコマンドでリベースを続行する. + +```bash +git add [修正したファイル] +git rebase --continue +``` + +全ての競合が解消されたらプッシュする.リベース後は履歴が書き換わるため `-f` オプションが必要になる. + +```bash +git push -f origin feature/new-function +``` + +### 間違えて main にコミットしてしまった場合 + +**まだプッシュしていない場合** + +コミットを取り消し,変更内容を保持したまま新しいブランチへ移動する. + +```bash +git reset --soft HEAD^ +git checkout -b feature/new-function +git commit -m "[add] ..." +``` + +**すでにプッシュしてしまった場合** + +`main` への force push はチーム全員の履歴を壊す危険があるため,自分では対処しない.直ちにチームメンバーに報告し,全員で対応方針を決める. diff --git "a/docs/01_GUIDE/GUIDE_05_\343\202\250\343\203\274\343\202\270\343\202\247\343\203\263\343\203\210\351\201\213\347\224\250\343\203\253\343\203\274\343\203\253.md" "b/docs/01_GUIDE/GUIDE_05_\343\202\250\343\203\274\343\202\270\343\202\247\343\203\263\343\203\210\351\201\213\347\224\250\343\203\253\343\203\274\343\203\253.md" new file mode 100644 index 0000000..9a30190 --- /dev/null +++ "b/docs/01_GUIDE/GUIDE_05_\343\202\250\343\203\274\343\202\270\343\202\247\343\203\263\343\203\210\351\201\213\347\224\250\343\203\253\343\203\274\343\203\253.md" @@ -0,0 +1,137 @@ +# エージェント運用ルール (Agent Operation Rules) + +実装品質を担保するために,3 つの専門エージェントを用いた開発パイプラインを定義する. + +## 基本方針 (Basic Policy) + +- 「実装完了」とは,コーディング・テスト・リファクタリングの全フェーズが完了した状態を指す. +- 各フェーズは専門エージェントが担当し,フレッシュなコンテキストでレビューする. +- フェーズのスキップは原則禁止する.リファクタリング不要の判断は Refactorer エージェント自身が行う. +- 各フェーズ間で人間が確認・判断を行う. + +## エージェント一覧 (Agent List) + +| エージェント | 役割 | フェーズ | +| --- | --- | --- | +| `coder` | 機能実装・バグ修正 | Phase 1 | +| `tester` | 仕様ベースのテスト作成・実行 | Phase 2 | +| `refactorer` | コード品質の改善 | Phase 3 | + +## 実装パイプライン (Implementation Pipeline) + +### 開始方法 + +```bash +/implement <タスク内容> +``` + +### 全体フロー + +``` +人間: /implement <タスク内容> + │ + ├─ ブランチ作成(GUIDE_04 準拠) + │ + ├─ Phase 1 ──▶ [Coder] + │ 実装に集中.テスト・リファクタは行わない + │ + ├─ 人間の確認ポイント 1 + │ ブラウザ/実機で動作確認 + │ OK → 続行 / NG → フィードバックして修正 + │ + ├─ Phase 2 ──▶ [Tester] + │ 仕様ベースでテスト作成・実行 + │ + ├─ Phase 2 完了後の分岐 + │ 全テスト成功 → 自動で Phase 3 へ + │ テスト失敗 → 人間に報告し判断を仰ぐ + │ + ├─ Phase 3 ──▶ [Refactorer] + │ テストを安全網としてリファクタリング + │ テスト再実行で挙動が変わっていないことを保証 + │ + ├─ Phase 4 ──▶ ドキュメント更新 + │ docs/ と CLAUDE.md を必要に応じて更新 + │ 更新がある場合のみ人間の確認を挟む + │ 結果を .claude/commit-context.md に書き出す + │ + └─ 完了 → /commit でコミット +``` + +### Phase 1: コーディング (Coding) + +- Coder エージェントが `docs/` を読んで実装する. +- 実装完了後,実装サマリーを出力する. +- テストやリファクタリングは行わない. +- コミットはしない. + +### 人間の確認ポイント 1 + +- ブラウザ・実機での動作確認(AI にはできない確認). +- 問題があればフィードバックし,Coder に修正を指示する. + +### Phase 2: テスト (Testing) + +- Tester エージェントが仕様(`docs/04_SPEC/`)を基準にテストを作成する. +- テストは実装コードではなく**仕様**を基準に書く. +- 実装が仕様と異なればテストが失敗し,バグを検出する. + +### Phase 2 完了後の分岐 + +- **全テスト成功**: テストサマリーを表示し,自動的に Phase 3 に進む. +- **テスト失敗あり**: 人間に報告し,判断を仰ぐ. + - 仕様の問題 → 仕様を修正 + - 実装の問題 → Coder に修正を委譲 + - テストの問題 → Tester に修正を委譲 + +### Phase 3: リファクタリング (Refactoring) + +- Refactorer エージェントがテストを安全網としてコード品質を改善する. +- 挙動は変更しない. +- リファクタリング後にテストを再実行し,全テストが通ることを確認する. +- リファクタリング不要と判断した場合は,理由を明示して終了する. + +### Phase 4: ドキュメント更新 (Documentation) + +Phase 3 完了後,実装内容に応じて `docs/` と `CLAUDE.md` を更新する. + +- **チェック観点**: + - API・データ構造の変更 → `docs/04_SPEC/` の該当仕様を更新 + - 環境・依存関係の変更 → `docs/02_ENV/` を更新 + - 開発ステップの進捗 → `docs/03_PLAN/` や `CLAUDE.md` の進捗欄を更新 + - 規約・運用ルールの変更 → `docs/01_GUIDE/` を更新 +- **該当なし**: ドキュメント更新が不要な変更(軽微なバグ修正,リファクタリングのみ等)はスキップ可. +- **更新がある場合のみ**人間の確認を挟む.更新不要の場合は確認なしで完了処理に進む. +- **コミットコンテキストの書き出し**: Phase 4 の結果(更新の有無と理由)を `.claude/commit-context.md` に書き出す.このファイルは `/commit` が参照し,docs/CLAUDE.md の更新漏れチェックをスキップするために使う(`.gitignore` 対象). + +### 完了処理 + +- `/implement` はコミットを行わない.完了後は `/commit` でコミットする. +- `/commit` は `.claude/commit-context.md` が存在する場合,docs/CLAUDE.md の更新漏れチェックをスキップする.存在しない場合(`/implement` を経由していない場合)は警告のみ行う. + +## コンテキスト受け渡し (Context Passing) + +各エージェントは前フェーズのサマリーを入力として受け取る.加えて `git diff` で実際の変更差分を自ら確認する. + +| フェーズ | 受け取る情報 | +| --- | --- | +| Coder | タスク内容 | +| Tester | Coder の実装サマリー + git diff | +| Refactorer | Coder + Tester のサマリー + git diff | + +## 人間の役割 (Human's Role) + +| タイミング | 人間がやること | +| --- | --- | +| 開始時 | タスクの指示(`/implement <何をするか>`) | +| Phase 1 後 | 動作確認(ブラウザ・実機など AI にできない確認) | +| Phase 2 後 | テスト失敗時のみ方針判断(全成功なら自動で Phase 3 へ) | +| Phase 4 後 | ドキュメント更新がある場合のみ確認 → `/commit` でコミット | + +人間の本質的な役割は「AI にできない判断と確認」であり,各フェーズの品質のゲートキーパーとなる. + +## コミットルール (Commit Rules) + +パイプライン完了後は `/commit` でコミットする.コミットメッセージのタグ等は [GUIDE_04](GUIDE_04_Git運用ルール.md) に従う. + +※ リファクタリングとテストは実装と一体の成果物として,まとめてコミットする.必要に応じて分割コミットも可.