GitHub Issueをローカルファイルとして管理するgh-issuefsを作った

TL;DR: GitHub IssueをローカルのMarkdownファイルとして同期するGitHub CLI拡張機能を作成。AIとの連携や計画駆動開発に最適。Projectsなどの機能に依存せず、ローカルでの柔軟な管理とGitHubとの同期を両立。

GitHub IssueをローカルのMarkdownファイルとして同期するGitHub CLI拡張機能gh-issuefsを作成しました。

はじめに

Twitter (X) で「Issueをレポジトリに含めればいい」という理論を見かけました。確かにIssueをコードと一緒に管理できるのは魅力的ですが、GitHub Projectsなどの機能が混ざってくると個人的には好きではありません。また、不要なファイルの削除などが面倒な上に、レポジトリには残ってしまいます。

そこで、Issueをローカルファイルとして管理するアプローチを取りました。これにより以下のメリットがあります：

• AIによる修正が楽になる: ローカルのMarkdownファイルとして管理することで、AIアシスタントが直接編集・理解しやすい
• 計画駆動開発: Issueから詳細な実装計画（.design/plan.md）を作成し、実装へと進めるワークフローが可能
• GitHubを単一の真実の情報源として維持: ローカルで編集してもGitHubと同期できる

gh-issuefsとは

gh-issuefsはGitHub Issueを.design/issues/配下のローカルMarkdownファイルとして同期するGitHub CLI拡張機能です。

.design/
  config.toml
  issues/
    123_add_login_error_handling/
      issue.md
      comments.json
      .meta.json

各IssueはYAML frontmatter付きのissue.mdとして保存されるため、コードと並べて編集・レビュー・管理が容易になります。

インストール

gh extension install sion908/gh-issuefs

ソースからビルドする場合

git clone https://github.com/sion908/gh-issuefs
cd gh-issuefs
go build -o gh-issuefs ./cmd/gh-issuefs
gh extension install .

使い方

初期化

gh issuefs init

.design/config.tomlが作成されます。

Issueの同期

GitHubからIssueをローカルに同期します。

# デフォルトクエリでpull
gh issuefs pull

# 番号を指定してpull
gh issuefs pull 123
gh issuefs pull 123 124 125

ローカル変更の反映

ローカルで編集したissue.mdをGitHubに反映します。

# 変更されたすべてのIssueをpush
gh issuefs push

# 指定したIssueをpush
gh issuefs push 123

# 変更内容を確認するだけで実際にはpushしない
gh issuefs push --dry-run

新規Issueの作成

テンプレートから新しいIssueディレクトリを生成し、GitHubに新規Issueを作成します。

# テンプレートからIssueディレクトリを生成
gh issuefs sample add_login_error_handling

# issue.mdを編集後、GitHubに新規Issueを作成
gh issuefs push --new

issue.mdのフォーマット

---
number: 123
title: ログインエラーハンドリングの追加
state: open
labels:
  - bug
assignees:
  - sion908
milestone: null
projects_v2:
  - name: My Project
    status: In Progress
---

## 概要

## 背景

## やること
- [ ]

## 完了条件
- [ ]

YAML frontmatterにメタデータを含めることで、AIが構造を理解しやすくなります。

AIとの連携

ローカルファイルとして管理することで、AIアシスタントとの連携がスムーズになります。

計画駆動開発のワークフロー

1. gh issuefs sampleでIssueディレクトリを生成
2. issue.mdを編集してタスクを定義
3. AIに.design/plan.mdの作成を依頼
4. AIに実装を依頼
5. gh issuefs pushでGitHubに反映

このワークフローにより、Issueから計画、実装までの一連の流れをAIと協力して進めることができます。

GitHub CLI拡張機能の作り方

gh-issuefsを作る過程で、GitHub CLI拡張機能が簡単に作れることを知りました。

基本的な手順は以下の通りです：

1. Goでコマンドラインツールを作成（gh-プレフィックスが必要）
2. gh extension install <repository>でインストール
3. gh <extension-name>で実行

詳細はGitHub CLI Extensionsのドキュメントを参照してください。

まとめ

gh-issuefsを使うことで、GitHub Issueをローカルファイルとして管理し、AIとの連携を強化できます。レポジトリにIssueを含めるアプローチとは異なり、ローカルでの柔軟な管理とGitHubとの同期を両立できます。

個人的には、このアプローチが計画駆動開発とAIアシストの両方に適していると感じています。

リンク

• GitHub Repository
• README