Back to Details

local-ticket-system

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

local-ticket-system

local-ticket-system

プロジェクトに 
.local/ticket/
ディレクトリベースのチケット管理システムをセットアップし、チケットの作成・管理を行う。
Set up a directory-based ticket management system in 
.local/ticket/
for your project to create and manage tickets.

Usage

Usage

以下のいずれかの状況で使用する:
  • プロジェクトにローカルチケット管理を新規導入したい
  • 既存のチケットシステムにタスク・バグ・チャプターチケットを追加したい
  • チケットのステータスを変更したい (done / closed / archived / deferred への移動)
Use in any of the following situations:
  • Want to newly introduce local ticket management to a project
  • Want to add task, bug, or chapter tickets to an existing ticket system
  • Want to change the status of a ticket (move to done / closed / archived / deferred)

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

Step 1: Setup (First time only)

プロジェクトに 
.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/
が存在する場合はスキップする。
If 
.local/ticket/
does not exist in the project, perform the following steps:
  1. Create the 
    .local/ticket/
    directory
  2. Copy 
    assets/about.md
    as 
    .local/ticket/about.md
  3. Copy 
    assets/task-0xx-template.md
    as 
    .local/ticket/task-0xx-template.md
  4. Copy 
    assets/chapter-template.md
    as 
    .local/ticket/chapter-template.md
  5. Add 
    .local/
    to 
    .gitignore
    if it is not already included
Skip if 
.local/ticket/
already exists.

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

Step 2: Determine Ticket Type

チケットを作成する前に、ユーザーの要件を分析して適切な種別を選択する。
Before creating a ticket, analyze the user's requirements and select the appropriate type.

種別の定義

Type Definitions

種別用途粒度
task1つの作業単位。実装してcommitできる粒度小〜中。1回の作業セッションで完了できる
bug既存の不具合の記録と修正小〜中。1つのバグに対して1チケット
chapter複数の task/bug をまとめる上位概念大。要件整理 → task/bug に分割して進める
TypePurposeGranularity
taskA single unit of work. Granularity that can be implemented and committedSmall to medium. Can be completed in one work session
bugRecord and fix existing defectsSmall to medium. One ticket per bug
chapterA high-level concept that groups multiple tasks/bugsLarge. Proceed by organizing requirements → splitting into tasks/bugs

判断基準

Decision Criteria

以下の順に確認する:
  1. 既存の不具合か? → 
    bug
  2. 複数の作業ステップに分割する必要があるか? → 
    chapter
    • 要件がまだ曖昧で、設計・検討が必要
    • 複数の画面・機能にまたがる変更
    • DB設計 + API + フロントエンドなど複数レイヤーの変更を伴う
  3. 1回の作業で完了できるか? → 
    task
迷ったらユーザーに確認する。chapter で切るべきものを task にすると、チケットが肥大化して管理しづらくなる。逆に task で済むものを chapter にすると、不要なオーバーヘッドが生じる。
Check in the following order:
  1. Is it an existing defect? → 
    bug
  2. Does it need to be split into multiple work steps? → 
    chapter
    • Requirements are still ambiguous, requiring design and consideration
    • Changes span multiple screens/features
    • Involves changes across multiple layers such as DB design + API + frontend
  3. Can it be completed in one work session? → 
    task
If unsure, confirm with the user. If you set something that should be a chapter as a task, the ticket will become bloated and difficult to manage. Conversely, setting something that can be a task as a chapter will create unnecessary overhead.

Step 3: チケットの作成

Step 3: Create Ticket

Step 2 で決定した種別に応じてチケットを作成する。
Create a ticket according to the type determined in Step 2.

命名規則

Naming Conventions

  • タスク: 
    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 は連番を使わない。
  • Task: 
    task-{3-digit serial number}-{slug}.md
    (example: 
    task-001-add-login.md
    )
  • Bug: 
    bug-{3-digit serial number}-{slug}.md
    (example: 
    bug-001-null-pointer.md
    )
  • Chapter: 
    chapter-{slug}.md
    (example: 
    chapter-multi-tenant.md
    )
For task / bug serial numbers, get the maximum number from existing tickets (including done/, closed/) in 
.local/ticket/
and add 1. Chapters do not use serial numbers.

タイトル形式

Title Format

チケット本文の 
# タイトル
行は、内容を表す絵文字 prefix を 1 つ先頭に付ける。 種別を問わず (task / bug / chapter いずれでも) 適用する。
例:
markdown
undefined
The 
# Title
line in the ticket body should start with one emoji prefix that represents the content. Apply this regardless of type (task / bug / chapter).
Example:
markdown
undefined

🗑️ 不要なコード削除

🗑️ Delete unnecessary code

✨ ログイン機能の追加

✨ Add login functionality

🐛 null pointer in user lookup

🐛 null pointer in user lookup

🏗️ マルチテナント対応 chapter

🏗️ Multi-tenant support chapter


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

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

You can basically choose any emoji that fits the content freely. If unsure, select from the reference table below.

| Emoji | Purpose |
|-------|---------|
| ✨ | New feature / feat |
| 🐛 | Bug fix / fix |
| 🗑️ | Delete unnecessary code/files |
| ♻️ | Refactoring |
| 📝 | Documentation |
| ✅ | Add/modify tests |
| 🎨 | Code style / formatting |
| ⚡ | Performance improvement |
| 🔧 | Configuration change |
| 🚧 | WIP / In progress |
| 🔥 | Large-scale deletion |
| 🔒 | Security fix |
| ⬆️ | Dependency upgrade |
| ⬇️ | Dependency downgrade |
| 🚀 | Deployment / release |
| 💄 | UI / style adjustment |
| 🏗️ | Architecture change / chapter |
| 🚨 | Fix lint warnings |
| 🔀 | Merge |
| 📦 | Packaging |
| 🧪 | Experimental feature |
| 🩹 | Minor fix |
| 💚 | CI fix |
| 📈 | Metrics / analytics |
| 🌐 | i18n / l10n |
| ♿ | Accessibility |
| 🏷️ | Type / type definition |
| 🚸 | UX improvement |
| 🩺 | Health check / diagnosis |

task チケットの構成

Task Ticket Structure

テンプレート (
assets/task-0xx-template.md
) をベースに、以下のセクションで構成する:
markdown
undefined
Based on the template (
assets/task-0xx-template.md
), structure it with the following sections:
markdown
undefined

{絵文字} タイトル

{emoji} Title

概要説明
Overview description

検証方法

Verification Method

動作確認の手順・コマンド
Steps/commands for operation verification

チェックリスト

Checklist

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

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

チェックリスト末尾の共通項目 (不要ファイル削除〜done 移動) は必ず含める。
  • Implementation task 1
  • Implementation task 2
  • Delete unnecessary files
  • Verification (perform items in the Verification Method section)
  • Self-review
  • commit
  • Move this ticket to done/

Select one `{emoji}` according to the "Title Format" section.

Be sure to include the common items at the end of the checklist (from deleting unnecessary files to moving to done).

bug チケットの構成

Bug Ticket Structure

task の構成に加え、以下を含める:
  • 再現手順 — 問題を再現する具体的な手順
  • 期待される動作 と 実際の動作
  • 推測される原因 — わかる範囲で
  • 対応方針の候補 — 複数案がある場合はリストアップ
In addition to the task structure, include the following:
  • Reproduction Steps — Specific steps to reproduce the issue
  • Expected Behavior and Actual Behavior
  • Suspected Cause — As much as you know
  • Candidate Response Strategies — List multiple options if available

chapter チケットの構成

Chapter Ticket Structure

テンプレート (
assets/chapter-template.md
) をベースに、以下のセクションで構成する:
markdown
undefined
Based on the template (
assets/chapter-template.md
), structure it with the following sections:
markdown
undefined

{絵文字} タイトル

{emoji} Title

やりたいこと

What We Want to Do

ざっくりとした目的・背景
Rough purpose and background

課題・モチベーション

Issues / Motivation

なぜこれをやりたいのか、現状の課題は何か
Why we want to do this, what are the current issues

スコープ（仮）

Scope (Tentative)

  • 大まかにやりたいことを箇条書き
  • Bullet points of roughly what we want to do

やらないこと（仮）

What We Won't Do (Tentative)

  • 明示的にスコープ外とするもの
  • Items explicitly out of scope

検討が必要な事項

Items Needing Consideration

  • 設計・実装前に決めないといけないこと
  • Things that must be decided before design/implementation

進め方

How to Proceed

  1. 要件・スコープの確定
  2. 設計（DB / API / 画面）
  3. 実装チケットへの分割（task-xxx, bug-xxx 等）
  4. 実装
  5. テスト・動作確認
  6. デプロイ
  1. Finalize requirements and scope
  2. Design (DB / API / screens)
  3. Split into implementation tickets (task-xxx, bug-xxx, etc.)
  4. Implementation
  5. Testing and operation verification
  6. Deployment

参考情報

Reference Information

  • 関連する既存チケット、ドキュメント、外部リンク等
undefined
  • Related existing tickets, documents, external links, etc.
undefined

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

Step 4: Ticket Status Management

task / bug のライフサイクル

Task / Bug Lifecycle

  1. 作成: 
    .local/ticket/
    直下に配置
  2. 作業中: チェックリストを消化しながら実装
  3. done: 実装・commit が完了 → 
    done/
    へ移動
  4. closed: 動作確認・検証が完了 → 
    closed/
    へ移動
  5. deferred: 意図的に後回し → 
    deferred/
    へ移動（再着手の意図あり）
ステータス変更はファイルの移動で行う:
bash
mv .local/ticket/task-001-add-login.md .local/ticket/done/
  1. Created: Place directly under 
    .local/ticket/
  2. In Progress: Implement while completing the checklist
  3. Done: Implementation and commit are complete → Move to 
    done/
  4. Closed: Operation verification and validation are complete → Move to 
    closed/
  5. Deferred: Intentionally postponed → Move to 
    deferred/
    (intention to resume later)
Change status by moving the file:
bash
mv .local/ticket/task-001-add-login.md .local/ticket/done/

chapter のライフサイクル

Chapter Lifecycle

  1. 作成: 
    .local/ticket/
    直下に配置
  2. 検討中: スコープや検討事項を詰めていく
  3. 分割: task / bug チケットに分割する。分割したチケット名を chapter 内に記録する
  4. archived: 全ての子チケットが done/closed になったら 
    archived/
    へ移動
  5. deferred: 着手を先送りにするとき → 
    deferred/
    へ移動
chapter は done/closed には移動しない。子チケットの完了が chapter の完了を意味する。
  1. Created: Place directly under 
    .local/ticket/
  2. Under Consideration: Refine scope and items needing consideration
  3. Split: Split into task / bug tickets. Record the names of split tickets in the chapter
  4. Archived: Move to 
    archived/
    when all child tickets are done/closed
  5. Deferred: When postponing start → Move to 
    deferred/
Chapters are not moved to done/closed. Completion of child tickets means completion of the chapter.

deferred/ への移動

Moving to deferred/

「今のフェーズでは着手しないが、将来再着手する意図がある」チケット・チャプターを置く場所。完了ではなく先送りを意味する。
移動前にチケット内に以下を追記する:
markdown
**Deferred 理由**: <なぜ後回しにするか>
**再起票 trigger**: <どういう条件で再着手するか>
**Deferred 日付**: YYYY-MM-DD
再着手するときは 
deferred/
から 
ticket/
直下に戻す。
A place to put tickets/chapters that "will not be started in the current phase but are intended to be resumed in the future". It means postponement, not completion.
Before moving, add the following to the ticket:
markdown
**Deferred Reason**: <Why it is being postponed>
**Reopen Trigger**: <Conditions for resuming work>
**Deferred Date**: YYYY-MM-DD
When resuming work, move it back from 
deferred/
to directly under 
ticket/
.