# Local Ticket System

> Markdown ベースのローカルチケット管理システムをプロジェクトにセットアップする。 .local/ticket/ ディレクトリにタスク・バグ・チャプターチケットを作成し、 チェックリスト形式で進捗を追跡する。Git 管理対象外のため気軽に使える。 言語・フレームワーク不問。 Use when requested: "チケットシステムを導入", "タスク管理を Markdown で", "ローカルチケット管理をセットアップ", "チケットを作成", "バグチケットを作成", "チャプターを作成", "epic を作成", "local ticket system", "setup ticket management".

- Skill: `tbsten/local-ticket-system` (Agent Skill, multi-file: 8 files)
- Install (CLI): `npx skillmds@latest add tbsten/local-ticket-system`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tbsten/local-ticket-system/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: tbsten (https://skillmd.com/u/tbsten)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tbsten/local-ticket-system

---


# local-ticket-system

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

## Usage

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

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

決定的な作業 (ディレクトリ作成・テンプレートコピー・連番算出・ファイル移動) は `scripts/` の script が行う。**script を読解・書き換え・再実装せず、そのまま実行する。** AI の責務は判断が必要な部分 — 種別の判断 (Step 2)、絵文字・タイトル・本文の記入 — に限る。各 script は失敗時に stderr へ `ERROR:` / `WHY:` / `FIX:` を出力するので、失敗したら `FIX:` に従う。

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

プロジェクトルートで `${CLAUDE_SKILL_DIR}/scripts/setup.sh` を実行する。

```bash
"${CLAUDE_SKILL_DIR}/scripts/setup.sh"
```

- `.local/ticket/` の作成、テンプレート (about.md / task / bug / chapter) のコピー、`done/` `closed/` `archived/` `deferred/` の作成、`.gitignore` への `.local/` 追記までをまとめて行う
- 冪等なので `.local/ticket/` が既にあるかの事前確認は不要。既存ファイルは上書きされない
- 成功時は stdout に 1 行 JSON (`{"ok":true,...}`) が出力される

## 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 で決定した種別に応じて `${CLAUDE_SKILL_DIR}/scripts/new-ticket.sh` でチケットファイルを作成する。連番の算出とテンプレートのコピーは script が行うので、手動で計算・コピーしない。

```bash
"${CLAUDE_SKILL_DIR}/scripts/new-ticket.sh" <task|bug|chapter> <slug>
# 例: new-ticket.sh task add-login → .local/ticket/task-042-add-login.md
```

- slug は小文字英数字とハイフン (例: `add-login`)
- 成功時は stdout に作成されたチケットのパスが 1 行出力される
- 作成後、そのファイルを開いて `TODO:` プレースホルダ (絵文字・タイトル・本文) を記入する。ここは AI の責務

### 命名規則 (script が自動適用)

- タスク: `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/, deferred/, archived/ 含む) から種別ごとに最大番号を取得し +1 する。chapter は連番を使わない。いずれも new-ticket.sh が自動算出する。

### タイトル形式

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

例:

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

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

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

### task チケットの構成

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

```markdown
# {絵文字} タイトル

概要説明

## 検証方法

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

## チェックリスト

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

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

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

### bug チケットの構成

テンプレート (`assets/bug-0xx-template.md`) をベースに、task の構成に加えて以下のセクションを含む:

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

### chapter チケットの構成

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

```markdown
# {絵文字} タイトル

## やりたいこと

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

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

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

## スコープ（仮）

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

## やらないこと（仮）

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

## 検討が必要な事項

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

## 進め方

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/` へ移動（再着手の意図あり）

ステータス変更は `${CLAUDE_SKILL_DIR}/scripts/move-ticket.sh` で行う。`mv` を手で組み立てない:

```bash
"${CLAUDE_SKILL_DIR}/scripts/move-ticket.sh" <ticket-file> <done|closed|deferred|archived>
# 例: move-ticket.sh .local/ticket/task-001-add-login.md done
```

- 成功時は stdout に 1 行 JSON (`{"ok":true,"from":...,"to":...}`) が出力される
- chapter を done / closed に移動しようとするとエラーになる (下記ライフサイクル参照)

### chapter のライフサイクル

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

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

### deferred/ への移動

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

`move-ticket.sh <ticket-file> deferred` を実行すると、移動前に以下の雛形がチケット末尾へ自動追記される (日付は実行日が入る):

```markdown
**Deferred 理由**: TODO:DeferredReason
**再起票 trigger**: TODO:ReopenTrigger
**Deferred 日付**: YYYY-MM-DD
```

移動後、`deferred/` 内のファイルを開いて `TODO:` プレースホルダを実際の理由・再起票 trigger に書き換える。ここは AI の責務。

再着手するときは `deferred/` から `ticket/` 直下に戻す (`mv` でよい)。