local-ticket-system

local-ticket-system

プロジェクトに .local/ticket/ ディレクトリベースのチケット管理システムをセットアップし、チケットの作成・管理を行う。

Usage

以下のいずれかの状況で使用する:

• プロジェクトにローカルチケット管理を新規導入したい
• 既存のチケットシステムにタスク・バグ・チャプターチケットを追加したい
• チケットのステータスを変更したい (done / closed / archived / deferred への移動)

Step 1: セットアップ (初回のみ)

プロジェクトに .local/ticket/ が存在しない場合、以下を実行する。

1. .local/ticket/ ディレクトリを作成
2. assets/about.md を .local/ticket/about.md としてコピー
3. assets/task-0xx-template.md を .local/ticket/task-0xx-template.md としてコピー
4. assets/chapter-template.md を .local/ticket/chapter-template.md としてコピー
5. .gitignore に .local/ が含まれていなければ追加

既に .local/ticket/ が存在する場合はスキップする。

Step 2: チケット種別の判断

チケットを作成する前に、ユーザーの要件を分析して適切な種別を選択する。

種別の定義

種別	用途	粒度
task	1つの作業単位。実装してcommitできる粒度	小〜中。1回の作業セッションで完了できる
bug	既存の不具合の記録と修正	小〜中。1つのバグに対して1チケット
chapter	複数の task/bug をまとめる上位概念	大。要件整理 → task/bug に分割して進める

判断基準

以下の順に確認する:

1. 既存の不具合か? → bug
2. 複数の作業ステップに分割する必要があるか? → chapter
   • 要件がまだ曖昧で、設計・検討が必要
   • 複数の画面・機能にまたがる変更
   • DB設計 + API + フロントエンドなど複数レイヤーの変更を伴う
3. 1回の作業で完了できるか? → task

迷ったらユーザーに確認する。chapter で切るべきものを task にすると、チケットが肥大化して管理しづらくなる。逆に task で済むものを chapter にすると、不要なオーバーヘッドが生じる。

Step 3: チケットの作成

Step 2 で決定した種別に応じてチケットを作成する。

命名規則

• タスク: task-{連番3桁}-{slug}.md (例: task-001-add-login.md)
• バグ: bug-{連番3桁}-{slug}.md (例: bug-001-null-pointer.md)
• チャプター: chapter-{slug}.md (例: chapter-multi-tenant.md)

task / bug の連番は .local/ticket/ 内の既存チケット (done/, closed/ 含む) から最大番号を取得し +1 する。chapter は連番を使わない。

タイトル形式

チケット本文の # タイトル 行は、内容を表す絵文字 prefix を 1 つ先頭に付ける。 種別を問わず (task / bug / chapter いずれでも) 適用する。

例:

# 🗑️ 不要なコード削除
# ✨ ログイン機能の追加
# 🐛 null pointer in user lookup
# 🏗️ マルチテナント対応 chapter

絵文字は内容に合うものを基本的に自由に選んでよい。迷った場合は下記の参考表から選ぶ。

絵文字	用途
✨	新機能 / feat
🐛	バグ修正 / fix
🗑️	不要なコード/ファイル削除
♻️	リファクタリング
📝	ドキュメント
✅	テスト追加・修正
🎨	コードスタイル / フォーマット
⚡	パフォーマンス改善
🔧	設定変更
🚧	WIP / 作業中
🔥	大規模削除
🔒	セキュリティ修正
⬆️	依存関係アップグレード
⬇️	依存関係ダウングレード
🚀	デプロイ・リリース
💄	UI / スタイル調整
🏗️	アーキテクチャ変更 / chapter
🚨	Lint 警告対応
🔀	マージ
📦	パッケージング
🧪	実験的機能
🩹	軽微な修正
💚	CI 修正
📈	計測・analytics
🌐	i18n / l10n
♿	アクセシビリティ
🏷️	型 / 型定義
🚸	UX 改善
🩺	ヘルスチェック / 診断

task チケットの構成

テンプレート (assets/task-0xx-template.md) をベースに、以下のセクションで構成する:

# {絵文字} タイトル

概要説明

## 検証方法

動作確認の手順・コマンド

## チェックリスト

- [ ] 実装タスク 1
- [ ] 実装タスク 2
- [ ] 不要ファイルの削除
- [ ] 検証（検証方法セクションの項目を実施）
- [ ] セルフレビュー
- [ ] commit
- [ ] このチケットを done/ に移動

{絵文字} は「タイトル形式」セクションに従って 1 つ選ぶ。

チェックリスト末尾の共通項目 (不要ファイル削除〜done 移動) は必ず含める。

bug チケットの構成

task の構成に加え、以下を含める:

• 再現手順 — 問題を再現する具体的な手順
• 期待される動作 と 実際の動作
• 推測される原因 — わかる範囲で
• 対応方針の候補 — 複数案がある場合はリストアップ

chapter チケットの構成

テンプレート (assets/chapter-template.md) をベースに、以下のセクションで構成する:

# {絵文字} タイトル

## やりたいこと

ざっくりとした目的・背景

## 課題・モチベーション

なぜこれをやりたいのか、現状の課題は何か

## スコープ（仮）

- 大まかにやりたいことを箇条書き

## やらないこと（仮）

- 明示的にスコープ外とするもの

## 検討が必要な事項

- [ ] 設計・実装前に決めないといけないこと

## 進め方

1. [ ] 要件・スコープの確定
2. [ ] 設計（DB / API / 画面）
3. [ ] 実装チケットへの分割（task-xxx, bug-xxx 等）
4. [ ] 実装
5. [ ] テスト・動作確認
6. [ ] デプロイ

## 参考情報

- 関連する既存チケット、ドキュメント、外部リンク等

Step 4: チケットのステータス管理

task / bug のライフサイクル

1. 作成: .local/ticket/ 直下に配置
2. 作業中: チェックリストを消化しながら実装
3. done: 実装・commit が完了 → done/ へ移動
4. closed: 動作確認・検証が完了 → closed/ へ移動
5. deferred: 意図的に後回し → deferred/ へ移動（再着手の意図あり）

ステータス変更はファイルの移動で行う:

mv .local/ticket/task-001-add-login.md .local/ticket/done/

chapter のライフサイクル

1. 作成: .local/ticket/ 直下に配置
2. 検討中: スコープや検討事項を詰めていく
3. 分割: task / bug チケットに分割する。分割したチケット名を chapter 内に記録する
4. archived: 全ての子チケットが done/closed になったら archived/ へ移動
5. deferred: 着手を先送りにするとき → deferred/ へ移動

chapter は done/closed には移動しない。子チケットの完了が chapter の完了を意味する。

deferred/ への移動

「今のフェーズでは着手しないが、将来再着手する意図がある」チケット・チャプターを置く場所。完了ではなく先送りを意味する。

移動前にチケット内に以下を追記する:

**Deferred 理由**: <なぜ後回しにするか>
**再起票 trigger**: <どういう条件で再着手するか>
**Deferred 日付**: YYYY-MM-DD

再着手するときは deferred/ から ticket/ 直下に戻す。