diff --git a/.claude/rules/docs-naming.md b/.claude/rules/docs-naming.md new file mode 100644 index 0000000..58751ea --- /dev/null +++ b/.claude/rules/docs-naming.md @@ -0,0 +1,35 @@ +--- +paths: ["docs/**"] +--- + +# ドキュメント管理・ファイル命名規則 (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 へのコンテキスト入力精度が向上する． +- スタイルの継承: 新規作成するファイルも，必ず [markdown-style](markdown-style.md) ルールに記載された書式に従うこと． diff --git a/.claude/rules/markdown-style.md b/.claude/rules/markdown-style.md new file mode 100644 index 0000000..b05a532 --- /dev/null +++ b/.claude/rules/markdown-style.md @@ -0,0 +1,118 @@ +--- +paths: ["**/*.md"] +--- + +# ドキュメント作成ガイドライン (Documentation Style Guide) + +本ルールはプロジェクト内のマークダウンドキュメントの書式を統一するためのルールを定める．Markdown ファイルを作成・編集するときは必ず従うこと． +基本方針として [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/.claude/rules/progress-log.md b/.claude/rules/progress-log.md new file mode 100644 index 0000000..90d826c --- /dev/null +++ b/.claude/rules/progress-log.md @@ -0,0 +1,64 @@ +--- +paths: ["CLAUDE.md", "docs/PROGRESS.md"] +--- + +# 進捗記録の運用ルール (Progress Log Rules) + +`CLAUDE.md` の「開発進捗」セクションと `docs/PROGRESS.md` を更新するときは本ルールに従うこと． + +> ⚠ **チーム開発モード（team）では本ルールは上書きされる**．team プロジェクトでは進捗を `CLAUDE.md`・`docs/PROGRESS.md` に書かず，GitHub Issues と git 履歴で追う（[GUIDE_06](../../docs/01_GUIDE/GUIDE_06_チーム開発ルール.md)）．以下は個人開発モード（solo）の既定ルールである．team モードでは Phase 4 の進捗更新を Issue コメント（`/task-handoff` 等）に置き換える． + +## 二段構成 (Two-tier Structure) + +進捗記録は **2 ファイルの二段構成**で管理する．`/implement` の Phase 4 や `/setup` 中断時にこれらを更新する． + +| ファイル | 役割 | 更新方法 | +| --- | --- | --- | +| `CLAUDE.md` の「開発進捗」セクション | **最新ステップ 1 行のみ**（毎ターン読み込まれる薄い目印） | 上書き | +| `docs/PROGRESS.md` | **追記型のフル進捗ログ**（動機・設計判断・失敗パターン含む） | 末尾に追記 | + +**背景**: CLAUDE.md は毎ターン読み込まれるため，追記型運用にするとコンテキスト圧迫の原因になる．一方で進捗の経緯・失敗パターン・設計判断はタスクを跨いで価値があるため捨てたくない．そこで「常に読まれる薄いポインタ（CLAUDE.md）」と「必要な時だけ読む厚いログ（PROGRESS.md）」に分離する．関数名・引数・テスト件数等の実装詳細は `git log` とコミットメッセージに完全な形で残るため，どちらにも書かない． + +## CLAUDE.md「開発進捗」の書き方 + +- **最新 1 行のみ**．古い行は上書きで消す（履歴は PROGRESS.md に残るので消えてよい） +- 基本形式: `最新: <ステップ見出し>` +- 関数名・テスト件数・実装手順詳細は書かない（PROGRESS.md と `git log` に任せる） + +## docs/PROGRESS.md の書き方 + +`docs/PROGRESS.md` は追記型．最新エントリを**末尾に追記**する（時系列順．古いものが上，新しいものが下）． + +**書く（PROGRESS.md に残す価値が高いもの）**: + +以下は PROGRESS.md に置く価値があるが，全て書く必要はない．シンプルなステップなら状況の 1 行だけで十分．書くことが少ない時に無理に伸ばさない． + +- 状況: 何が完了したか（1 行） +- 動機・原因: なぜそれをやったか（既存の問題点・要件変更・前バージョンの欠点など） +- 重要な設計判断: 他案との比較が必要な場合のみ．「A 案ではなく B 案を選んだ理由」が将来の判断材料になるとき +- 失敗パターンの圧縮サマリ: 「① X 案 → Y で破綻 / ② Z 案で解決」のような 1〜2 行．同じ轍を踏まないための知識として残す．試行錯誤を時系列で全部書かず，本質的に異なるアプローチの失敗だけを並列項目として記録する +- 未実装・後段: 「次に何をすべきか」を思い出すための短いメモ + +**書かない（コミットメッセージと `git log` に任せる）**: + +以下は `git log ` または `git show ` で完全な情報が取れる．PROGRESS.md に書くと重複・陳腐化する． + +- 関数名・引数・型シグネチャ +- テスト件数の内訳（合計件数のみなら可だが数字は陳腐化するので省略推奨） +- リファクタリングの手順詳細 +- 撤去・新規追加の関数リスト +- 具体的な定数値・閾値（設計判断の核心に関わるものを除く） +- 数値範囲の細部（実装パラメータ等） +- 後方互換性の細かい仕様 +- 「全テスト N passed」の報告（pass している前提のため不要） + +**長さと書式**: + +- 1 エントリの長さは内容次第で可変．書くことが少なければ **1 行で十分**．複数系統の作業を 1 ステップにまとめた等で必要なら長くなってもよい．無理に伸ばさず無理に削らず，「未来の自分（または他人）が辿れるか」だけを基準にする +- 基本形式: `- [x] **<簡潔な見出し>**: <1〜2 文の要約>`．必要に応じて下に動機・設計判断・失敗パターンを 1〜2 行ずつ追加 +- 太字は**見出しに使う**（目次の項目として目立たせる）．本文中で多用しない +- 長い箇条書きを避ける．箇条書きは「失敗パターン ① ② ③」のような本質的に異なる選択肢の並列項目に限定する + +**既存エントリの長文化に気付いたとき**: + +過去のエントリで「詳細をベタ書きしていて目次として機能しなくなっている」ものを見つけたら，ユーザーに圧縮を提案する．自動で削らない（背景情報の価値判断はユーザーが行う）．提案時は「この情報は `git log` にあるので削れる / これは失敗パターンなので残すべき」のように切り分けて示すこと． diff --git a/.claude/skills/auto-refactor/SKILL.md b/.claude/skills/auto-refactor/SKILL.md index 8a02eb3..36fcdb8 100644 --- a/.claude/skills/auto-refactor/SKILL.md +++ b/.claude/skills/auto-refactor/SKILL.md @@ -7,7 +7,7 @@ あなたは**自律リファクタリング＆ドキュメント同期ループの制御層（オーケストレータ）**です． ユーザーが席を外している無人時間に，空いた稼働枠を「コードの大規模リファクタリング」と「実装とドキュメントのズレ解消」に充てるために起動されました． -GUIDE_02（ドキュメント作成），GUIDE_04（Git 運用），GUIDE_05（エージェント運用）を読み，書式・規約・パイプラインのルールを理解した上で，以下の不変条件を厳守してループを回してください． +GUIDE_04（Git 運用），GUIDE_05（エージェント運用）と，ドキュメント書式・命名のルール（`.claude/rules/markdown-style.md`・`.claude/rules/docs-naming.md`）を読み，書式・規約・パイプラインのルールを理解した上で，以下の不変条件を厳守してループを回してください． このループが扱う作業は **4 種類**ある．前の3種をすべて拾い尽くした後にだけ，最後の「テストリファクタ系」を行う（最も安全網が特殊で危険なため，最後に回す）． @@ -206,7 +206,7 @@ #### ステップ D2: 追記（自動／実装を真とする） -- 実装を真として，該当ドキュメント（`02_ENV`／`04_SPEC`／`05_TECH` の適切な場所）に**事実を追記・補足**する．GUIDE_02 のドキュメント作成規約と GUIDE_03 の命名規則に従う． +- 実装を真として，該当ドキュメント（`02_ENV`／`04_SPEC`／`05_TECH` の適切な場所）に**事実を追記・補足**する．書式は `.claude/rules/markdown-style.md`，命名は `.claude/rules/docs-naming.md` に従う． - **既存の意図的な記述は消さない**．追記・補完にとどめ，全面書き換えはしない． - コミット（GUIDE_04 準拠）: - 新規セクション／新規ドキュメントファイルの追加 → タグ **`[add]`**（例: `[add] 04_SPEC に〇〇APIの仕様を追記`）． @@ -228,12 +228,12 @@ 選んだ箇所について，意味・情報を保ったまま改善できるかを判定する（不変条件 11）． - **無損失整形 or 意味を保った簡潔化/集約** → ステップ DR2 へ（自動で実施）． - - 例：冗長な言い回しを短くする，表記揺れ・カタカナ/英字のゆれを統一，見出しレベル・表・コードフェンス・箇条書きの整形，重複説明を1か所に集約して他はリンク，切れたリンクや古い参照（GUIDE_03 命名）を実在パスに修正，明らかなタイポ修正． + - 例：冗長な言い回しを短くする，表記揺れ・カタカナ/英字のゆれを統一，見出しレベル・表・コードフェンス・箇条書きの整形，重複説明を1か所に集約して他はリンク，切れたリンクや古い参照（`.claude/rules/docs-naming.md` の命名に照らす）を実在パスに修正，明らかなタイポ修正． - **情報が落ちる削除・大規模再編**（陳腐化記述の削除，ファイル分割/統合，節の大幅な並べ替え等） → ステップ DR3 へ（自動では行わず提案のみ）． #### ステップ DR2: ドキュメントリファクタ実施（自動） -- 該当ドキュメントを，**意味・決定事項・設計判断・失敗パターン・具体的制約を一切落とさずに**整形・簡潔化する．GUIDE_02（ドキュメント作成）・GUIDE_03（命名）に従う． +- 該当ドキュメントを，**意味・決定事項・設計判断・失敗パターン・具体的制約を一切落とさずに**整形・簡潔化する．`.claude/rules/markdown-style.md`（書式）・`.claude/rules/docs-naming.md`（命名）に従う． - 迷ったら削らない（残す側に倒す）．少しでも情報が落ちる懸念があれば DR3 に回す． - GUIDE_04 のコミット書式に従い，タグ **`[clean]`** でコミットする（例: `[clean] 04_SPEC の冗長な説明を簡潔化`）．`done` として返す． diff --git a/.claude/skills/implement/SKILL.md b/.claude/skills/implement/SKILL.md index aec0281..0dd1f3e 100644 --- a/.claude/skills/implement/SKILL.md +++ b/.claude/skills/implement/SKILL.md @@ -75,7 +75,7 @@ ## Phase 4: ドキュメント更新 (Documentation) -GUIDE_05 の「Phase 4: ドキュメント更新」に記載されたチェック観点に従い，`docs/`, `CLAUDE.md`, `docs/PROGRESS.md` を必要に応じて更新する．進捗を記録する場合は GUIDE_05「進捗記録の運用ルール（CLAUDE.md / PROGRESS.md）」に従う（CLAUDE.md は最新 1 行に上書き，`docs/PROGRESS.md` に詳細を末尾追記．`git log` で取れる詳細は書かない）． +GUIDE_05 の「Phase 4: ドキュメント更新」に記載されたチェック観点に従い，`docs/`, `CLAUDE.md`, `docs/PROGRESS.md` を必要に応じて更新する．進捗を記録する場合は進捗記録ルール `.claude/rules/progress-log.md` に従う（CLAUDE.md は最新 1 行に上書き，`docs/PROGRESS.md` に詳細を末尾追記．`git log` で取れる詳細は書かない）． Phase 4 の結果を `.claude/commit-context.md` に書き出す: diff --git a/.claude/skills/set-mode/SKILL.md b/.claude/skills/set-mode/SKILL.md index 8efe57c..dc3444e 100644 --- a/.claude/skills/set-mode/SKILL.md +++ b/.claude/skills/set-mode/SKILL.md @@ -137,7 +137,7 @@ ## 開発進捗 最新: <直近の状況を 1 行．不明なら「（git 履歴 / 旧 Issue を参照）」> - ※ 本欄は**最新ステップ 1 行のみ上書き更新**．詳細な進捗履歴は docs/PROGRESS.md に追記する．運用ルールは GUIDE_05 参照． + ※ 本欄は**最新ステップ 1 行のみ上書き更新**．詳細な進捗履歴は docs/PROGRESS.md に追記する．運用ルールは .claude/rules/progress-log.md 参照． ``` 「最新」行に入れる現状はユーザーに確認する（team 期間の進捗は Issues / git 履歴にあるため，ここへ移し替える必要はない）． - **「チーム開発（GUIDE_06 準拠）」小節を削除**する． diff --git a/.claude/skills/setup/SKILL.md b/.claude/skills/setup/SKILL.md index b6b205b..d159853 100644 --- a/.claude/skills/setup/SKILL.md +++ b/.claude/skills/setup/SKILL.md @@ -12,7 +12,7 @@ - 各フェーズの成果物をユーザーが承認してから次のフェーズに進むこと - ユーザーが「今日はここまで」と言った場合，CLAUDE.md の進捗（最新 1 行）と `docs/PROGRESS.md`（追記）を更新して中断する -- ドキュメントは GUIDE_02（ドキュメント作成ガイド）と GUIDE_03（ファイル命名規則）に従って作成する +- ドキュメントの書式・命名は `.claude/rules/markdown-style.md`・`.claude/rules/docs-naming.md` に従って作成する（該当ファイル編集時に自動ロードされる） - 成果物のドラフトを提示し，ユーザーの修正指示を反映してからファイルに書き出す - フォルダは成果物を実際に書き出すときにのみ作成する．空のカテゴリフォルダを先回りで作らない @@ -88,7 +88,7 @@ ### フォルダ作成の注意 -成果物を書き出すフォルダのみ作成する．GUIDE_03 のカテゴリ表は「あり得るカテゴリの一覧」であり，立ち上げ時に全カテゴリのフォルダを scaffold するものではない．GUIDE_01 の立ち上げフェーズで成果物が発生するのは `01_GUIDE / 02_ENV / 03_PLAN / 04_SPEC` のみ．`05_TECH/`（技術設計）と `06_TEST/`（テスト）は立ち上げ時には成果物が無いため，空フォルダを作らない（実装フェーズで必要になった時点で作成する）． +成果物を書き出すフォルダのみ作成する．`.claude/rules/docs-naming.md` のカテゴリ表は「あり得るカテゴリの一覧」であり，立ち上げ時に全カテゴリのフォルダを scaffold するものではない．GUIDE_01 の立ち上げフェーズで成果物が発生するのは `01_GUIDE / 02_ENV / 03_PLAN / 04_SPEC` のみ．`05_TECH/`（技術設計）と `06_TEST/`（テスト）は立ち上げ時には成果物が無いため，空フォルダを作らない（実装フェーズで必要になった時点で作成する）． ### フェーズ 3（環境構築）の注意 diff --git a/.claude/skills/sync-template/SKILL.md b/.claude/skills/sync-template/SKILL.md index deb92e8..6709a3c 100644 --- a/.claude/skills/sync-template/SKILL.md +++ b/.claude/skills/sync-template/SKILL.md @@ -396,5 +396,5 @@ - チーム層ファイル（`GUIDE_06`／`GUIDE_07`／`task-*`／`check_sync.sh`）は `.claude/project-mode` が `team` のプロジェクトにのみ同期する．`solo`（または未設定）のプロジェクトには配置・更新・削除いずれもしない．`/sync-template` は「版の追従」のみを行い，**モードの切り替えはしない**．solo↔team の切替は `/set-mode ` を使う（team 層ファイルの配置／削除・`settings.json` 配線・`CLAUDE.md` の team 化／solo 化・`project-mode` 更新を一括で行う）．`.claude/project-mode` を手で書き換えるだけでは切り替わらない - `.claude/settings.json` はマージ必須ファイル．team の SessionStart(check_sync) 配線を保持したままテンプレートの hook 変更を統合する．盲目的な `cp` で上書きしない - 通常コピー対象でもプロジェクト固有の変更が上書きされうる場合は，`git diff` で確認してユーザーに報告する -- テンプレートが管理するのは `.claude/` 配下のうち `agents/`，`skills/`，`hooks/`，`settings.json`，`template-sync-sha` のみ．`.claude/plans/` や `.claude/commit-context.md` 等のプロジェクト固有ファイルはテンプレートに含まれないため同期対象外 +- テンプレートが管理するのは `.claude/` 配下のうち `agents/`，`skills/`，`rules/`，`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.md b/CLAUDE.md index a69ad18..d427f49 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -5,7 +5,7 @@ ## 開発進捗 最新: GUIDE_01 に従いプロジェクト立ち上げ中 -※ 本欄は**最新ステップ 1 行のみ上書き更新**．詳細な進捗履歴（動機・設計判断・失敗パターン）は [docs/PROGRESS.md](docs/PROGRESS.md) に追記する．運用ルールは GUIDE_05「進捗記録の運用ルール（CLAUDE.md / PROGRESS.md）」を参照． +※ 本欄は**最新ステップ 1 行のみ上書き更新**．詳細な進捗履歴（動機・設計判断・失敗パターン）は [docs/PROGRESS.md](docs/PROGRESS.md) に追記する．運用ルールは `.claude/rules/progress-log.md` を参照（該当ファイル編集時に自動ロードされる）． ## 必須ルール（コード実装時） @@ -43,10 +43,9 @@ ### 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 +- ※ ドキュメント書式・命名規則・進捗記録は `.claude/rules/`（markdown-style / docs-naming / progress-log）に定義されており，該当ファイルの編集時に自動ロードされる - ※ コーディング規約，テスト方針等はプロジェクト立ち上げ時に作成する（GUIDE_01 参照） ### 02_ENV（環境） diff --git a/README.md b/README.md index ffc91c9..6dec367 100644 --- a/README.md +++ b/README.md @@ -48,9 +48,9 @@ `docs/01_GUIDE/` にプロジェクト運用の規約・ルールが置かれている．`/setup` を実行すれば AI がこれらを順次参照しながら立ち上げを進める． - `GUIDE_01_プロジェクト立ち上げフロー.md` — 立ち上げの 7 フェーズ（方針決定 → 実装開始） -- `GUIDE_02_ドキュメント作成ガイド.md` — 設計ドキュメントの書き方 -- `GUIDE_03_ファイル命名規則.md` — ファイル名の規則 - `GUIDE_04_Git運用ルール.md` — ブランチ・コミット・PR の運用 - `GUIDE_05_エージェント運用ルール.md` — `/implement` のエージェントチーム運用 - `GUIDE_06_チーム開発ルール.md` — **team モードのみ**．直列運用・条件付きセルフマージ・共有設定の扱い - `GUIDE_07_Issues・Projects運用ガイド.md` — **team モードのみ**．`gh` による Issue/Project 操作手順 + +ドキュメントの書式・ファイル命名・進捗記録のルールは `.claude/rules/`（`markdown-style` / `docs-naming` / `progress-log`）にあり，該当ファイルの編集時に Claude へ自動ロードされる． 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" index a6f9a0c..9e7e35b 100644 --- "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" @@ -63,7 +63,7 @@ - **基本方針**: 言語・フレームワークの公式ガイドラインや広く採用されている標準規約に則る（例: Effective Dart，PEP 8，Google Style Guide 等）．プロジェクト固有のルールは標準と異なる部分のみ定義する． - **人間が決めること**: 標準規約でカバーされない判断（アーキテクチャパターンの選択等） - **AI に依頼できること**: 標準規約を踏まえた規約のドラフト作成，参照元ガイドラインの調査 -- **作成すべきガイド**（推奨番号は GUIDE_03 に準拠）: +- **作成すべきガイド**（命名は `.claude/rules/docs-naming.md` に準拠）: - `GUIDE_06` コーディング規約 — 命名規則，フォーマット，import 順序，型の使い方，コメントの書き方，コード内ドキュメントの規則 - `GUIDE_07` ディレクトリ構造規則 — プロジェクトのディレクトリ構成とファイル配置ルール - `GUIDE_08` テスト方針 — テストの種類，粒度，実行タイミング，カバレッジ基準，モック方針，テストファイルの配置規則 @@ -83,7 +83,7 @@ 開発計画に沿って AI と協働で実装を進める． -- 各ステップの完了時に [GUIDE_02_ドキュメント作成ガイド](GUIDE_02_ドキュメント作成ガイド.md) と [GUIDE_04_Git運用ルール](GUIDE_04_Git運用ルール.md) に従ってコミット・PR を作成する． +- 各ステップの完了時に [GUIDE_04_Git運用ルール](GUIDE_04_Git運用ルール.md) に従ってコミット・PR を作成する（ドキュメント書式は `.claude/rules/markdown-style.md` が自動適用される）． - 仕様変更が発生した場合は，先にドキュメントを更新してから実装に反映する． ## CLAUDE.md の管理 (CLAUDE.md Management) @@ -94,7 +94,7 @@ ### 記載すべき内容 - **プロジェクト概要**: プロジェクト名，目的，技術スタックの要約 -- **開発進捗**: 現在のステップ（最新 1 行のみ）．詳細な進捗履歴は `docs/PROGRESS.md` に追記する（[GUIDE_05](GUIDE_05_エージェント運用ルール.md) の「進捗記録の運用ルール（CLAUDE.md / PROGRESS.md）」参照） +- **開発進捗**: 現在のステップ（最新 1 行のみ）．詳細な進捗履歴は `docs/PROGRESS.md` に追記する（進捗記録ルール `.claude/rules/progress-log.md` 参照） - **必須ルール**: AI が実装時に必ず守るべきルール（コーディング規約，コミット前チェック等の要点） - **ドキュメント一覧**: docs/ 内のファイルへの参照パス @@ -107,5 +107,5 @@ ### 運用上の注意 - CLAUDE.md は AI が毎回読み込むため，簡潔に保つ．詳細は docs/ のドキュメントに委ね，CLAUDE.md には要点と参照先のみ記載する． -- 進捗記録は二段構成（CLAUDE.md = 最新 1 行 / `docs/PROGRESS.md` = 追記型フルログ）で管理する．詳細は [GUIDE_05](GUIDE_05_エージェント運用ルール.md) を参照． +- 進捗記録は二段構成（CLAUDE.md = 最新 1 行 / `docs/PROGRESS.md` = 追記型フルログ）で管理する．詳細は `.claude/rules/progress-log.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" deleted file mode 100644 index ed91906..0000000 --- "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" +++ /dev/null @@ -1,114 +0,0 @@ -# ドキュメント作成ガイドライン (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" deleted file mode 100644 index f9d43d2..0000000 --- "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" +++ /dev/null @@ -1,31 +0,0 @@ -# ドキュメント管理・ファイル命名規則 (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_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" index 0c2ef4d..975f478 100644 --- "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" @@ -98,7 +98,7 @@ - **チェック観点**: - API・データ構造の変更 → `docs/04_SPEC/` の該当仕様を更新 - 環境・依存関係の変更 → `docs/02_ENV/` を更新 - - 開発ステップの進捗 → `docs/03_PLAN/` や進捗記録（`CLAUDE.md` の進捗欄＋ `docs/PROGRESS.md`）を更新（書式は本ガイドの「進捗記録の運用ルール（CLAUDE.md / PROGRESS.md）」に従う．`git log` で取れる詳細は書かない） + - 開発ステップの進捗 → `docs/03_PLAN/` や進捗記録（`CLAUDE.md` の進捗欄＋ `docs/PROGRESS.md`）を更新（書式は進捗記録ルール `.claude/rules/progress-log.md` に従う．`git log` で取れる詳細は書かない） - 規約・運用ルールの変更 → `docs/01_GUIDE/` を更新 - **該当なし**: ドキュメント更新が不要な変更（軽微なバグ修正，リファクタリングのみ等）はスキップ可． - **更新がある場合のみ**人間の確認を挟む．更新不要の場合は確認なしで完了処理に進む． @@ -143,57 +143,4 @@ ## 進捗記録の運用ルール（CLAUDE.md / PROGRESS.md） -> ⚠ **チーム開発モード（team）では本節は上書きされる**．team プロジェクトでは進捗を `CLAUDE.md`・`docs/PROGRESS.md` に書かず，GitHub Issues と git 履歴で追う（[GUIDE_06](GUIDE_06_チーム開発ルール.md)）．以下は個人開発モード（solo）の既定ルールである．team モードでは Phase 4 の進捗更新を Issue コメント（`/task-handoff` 等）に置き換える． - -進捗記録は **2 ファイルの二段構成**で管理する．Phase 4 や `/setup` 中断時にこれらを更新する． - -| ファイル | 役割 | 更新方法 | -| --- | --- | --- | -| `CLAUDE.md` の「開発進捗」セクション | **最新ステップ 1 行のみ**（毎ターン読み込まれる薄い目印） | 上書き | -| `docs/PROGRESS.md` | **追記型のフル進捗ログ**（動機・設計判断・失敗パターン含む） | 末尾に追記 | - -**背景**: CLAUDE.md は毎ターン読み込まれるため，追記型運用にするとコンテキスト圧迫の原因になる．一方で進捗の経緯・失敗パターン・設計判断はタスクを跨いで価値があるため捨てたくない．そこで「常に読まれる薄いポインタ（CLAUDE.md）」と「必要な時だけ読む厚いログ（PROGRESS.md）」に分離する．関数名・引数・テスト件数等の実装詳細は `git log` とコミットメッセージに完全な形で残るため，どちらにも書かない． - -### CLAUDE.md「開発進捗」の書き方 - -- **最新 1 行のみ**．古い行は上書きで消す（履歴は PROGRESS.md に残るので消えてよい） -- 基本形式: `最新: <ステップ見出し>` -- 関数名・テスト件数・実装手順詳細は書かない（PROGRESS.md と `git log` に任せる） - -### docs/PROGRESS.md の書き方 - -`docs/PROGRESS.md` は追記型．最新エントリを**末尾に追記**する（時系列順．古いものが上，新しいものが下）． - -**書く（PROGRESS.md に残す価値が高いもの）**: - -以下は PROGRESS.md に置く価値があるが，全て書く必要はない．シンプルなステップなら状況の 1 行だけで十分．書くことが少ない時に無理に伸ばさない． - -- 状況: 何が完了したか（1 行） -- 動機・原因: なぜそれをやったか（既存の問題点・要件変更・前バージョンの欠点など） -- 重要な設計判断: 他案との比較が必要な場合のみ．「A 案ではなく B 案を選んだ理由」が将来の判断材料になるとき -- 失敗パターンの圧縮サマリ: 「① X 案 → Y で破綻 / ② Z 案で解決」のような 1〜2 行．同じ轍を踏まないための知識として残す．試行錯誤を時系列で全部書かず，本質的に異なるアプローチの失敗だけを並列項目として記録する -- 未実装・後段: 「次に何をすべきか」を思い出すための短いメモ - -**書かない（コミットメッセージと `git log` に任せる）**: - -以下は `git log ` または `git show ` で完全な情報が取れる．PROGRESS.md に書くと重複・陳腐化する． - -- 関数名・引数・型シグネチャ -- テスト件数の内訳（合計件数のみなら可だが数字は陳腐化するので省略推奨） -- リファクタリングの手順詳細 -- 撤去・新規追加の関数リスト -- 具体的な定数値・閾値（設計判断の核心に関わるものを除く） -- 数値範囲の細部（実装パラメータ等） -- 後方互換性の細かい仕様 -- 「全テスト N passed」の報告（pass している前提のため不要） - -**長さと書式**: - -- 1 エントリの長さは内容次第で可変．書くことが少なければ **1 行で十分**．複数系統の作業を 1 ステップにまとめた等で必要なら長くなってもよい．無理に伸ばさず無理に削らず，「未来の自分（または他人）が辿れるか」だけを基準にする -- 基本形式: `- [x] **<簡潔な見出し>**: <1〜2 文の要約>`．必要に応じて下に動機・設計判断・失敗パターンを 1〜2 行ずつ追加 -- 太字は**見出しに使う**（目次の項目として目立たせる）．本文中で多用しない -- 長い箇条書きを避ける．箇条書きは「失敗パターン ① ② ③」のような本質的に異なる選択肢の並列項目に限定する - -**既存エントリの長文化に気付いたとき**: - -過去のエントリで「詳細をベタ書きしていて目次として機能しなくなっている」ものを見つけたら，ユーザーに圧縮を提案する．自動で削らない（背景情報の価値判断はユーザーが行う）．提案時は「この情報は `git log` にあるので削れる / これは失敗パターンなので残すべき」のように切り分けて示すこと． +進捗記録（CLAUDE.md「開発進捗」・`docs/PROGRESS.md` の書き方）のルールは `.claude/rules/progress-log.md` に定義されている．該当ファイルを編集する際に自動で読み込まれる． diff --git "a/docs/01_GUIDE/GUIDE_06_\343\203\201\343\203\274\343\203\240\351\226\213\347\231\272\343\203\253\343\203\274\343\203\253.md" "b/docs/01_GUIDE/GUIDE_06_\343\203\201\343\203\274\343\203\240\351\226\213\347\231\272\343\203\253\343\203\274\343\203\253.md" index d486527..ced842f 100644 --- "a/docs/01_GUIDE/GUIDE_06_\343\203\201\343\203\274\343\203\240\351\226\213\347\231\272\343\203\253\343\203\274\343\203\253.md" +++ "b/docs/01_GUIDE/GUIDE_06_\343\203\201\343\203\274\343\203\240\351\226\213\347\231\272\343\203\253\343\203\274\343\203\253.md" @@ -11,7 +11,7 @@ - 全員が Claude Code で開発し，実装はエージェントが行う（チーム規模はプロジェクトによる）． - 原則として並行作業を行わず，1 人ずつ直列で開発する．急ぎではないため，スループットより単純さと `main` の整合性を優先する．これは禁止ではなく既定のスタンスであり，状況に応じた判断は妨げない（詳細は「作業の直列化」）． - 人間の本質的な役割は「AI にできない判断と確認」（GUIDE_05 と同じ）．加えて「共有設定の番人」を担う． -- 進捗・タスクは GitHub Issues と git 履歴で追う．`CLAUDE.md` には進捗を書かない（この点は GUIDE_05 の進捗記録ルールを**上書き**する）． +- 進捗・タスクは GitHub Issues と git 履歴で追う．`CLAUDE.md` には進捗を書かない（この点は solo 既定の進捗記録ルール `.claude/rules/progress-log.md` を**上書き**する）． - `main` は常に動作可能な状態を保つ（GUIDE_04）．壊れたら他の作業より優先して直す． ## タスク管理 (Task Management) diff --git a/docs/PROGRESS.md b/docs/PROGRESS.md index 14ea2fc..68e9e62 100644 --- a/docs/PROGRESS.md +++ b/docs/PROGRESS.md @@ -6,6 +6,6 @@ - 最新エントリは下に追記する（時系列順．古いものが上，新しいものが下） - CLAUDE.md の「開発進捗」セクションは最新 1 行のみ（上書き運用） - 詳細・失敗パターン・設計判断はすべて本ファイルに残す -- 書式・運用ルールは docs/01_GUIDE/GUIDE_05_エージェント運用ルール.md - 「進捗記録の運用ルール（CLAUDE.md / PROGRESS.md）」を参照 +- 書式・運用ルールは .claude/rules/progress-log.md を参照 + （本ファイルの編集時に自動ロードされる） -->