Tasks as Code: チケットをリポジトリに移行する

Tasks as Code: チケットをリポジトリに移行する

AIコーディングエージェントはリポジトリから作業するため、チケットをJiraに保管し続けるのはなぜでしょうか？タスクをGit内のMarkdownとして保存し、コードやドキュメントの隣に置く方法を学びましょう。

AIコーディングエージェントは、必要なものがすべてリポジトリ内に存在する場合に最も効果的に機能します。なぜなら、コードがそれらのエージェントの真実の源となるからです。しかし、ほとんどのチームは依然としてJiraやRedmineのような、リポジトリの外にあるツールでタスクや要件を追跡しています。タスクを単純なMarkdownファイルとして保存することで、この状況は変わります。エージェントは、要件とコードを1つの場所で読み取ることができ、すべてのタスクの変更は、他のコミットと同様にバージョン管理され、レビュー可能になります。「Docs as Code」のアプローチは、この進化の青写真を提供しており、Gitと同期するWebインターフェースがあれば、テクニカルライターやプロダクトオーナーはコマンドラインに強制されることなく、最新情報を把握できます。

Docs as Code

ドキュメンテーションはすでに、個別のドキュメンテーションソフトウェアからGitリポジトリ内のMarkdownファイルへと移行しました。今日では、コードリポジトリ内の /docs フォルダに格納されることがよくあります。この実践は「Docs as Code または Docs Like Code」として知られています。

AIコーディングエージェントが登場したことで、このアプローチはさらに有用になります。エージェントはドキュメントを読み取ってシステムを理解し、コードを変更し、同じワークフローの一部として関連するドキュメントを更新できます。ドキュメンテーションは、後で完了する必要がある別の活動ではなく、ソフトウェア開発の不可欠な一部となります。

Tasks as Code

開発タスクにも同じ原則が適用されます。タスクがMarkdownファイルとして保存されると、エージェントはそれらを直接読み取り、作業計画に使用し、結果を同じファイルに記録できます。Gitは、ソフトウェアとドキュメンテーションの履歴とともに、タスクの履歴にもアクセスできるようにします。

この考え方は、すでにSpec-Driven Development (SDD)に反映されています。SDDは、AIエージェントが実装する前に意図された動作を定義するためにMarkdown形式の仕様を使用します。タスクファイルは同様の目的を果たせますが、詳細のレベルは作業によって異なります。小さなメンテナンスタスクは短い説明で済むかもしれませんが、複雑な機能には受け入れ基準、技術的な決定、依存関係、およびテスト要件が必要になる場合があります。

SDDはしばしばSpec Kitのような専用ツールによってサポートされますが、開始するにはよりシンプルなアプローチで十分です。タスクファイル自体を仕様として扱います。これにより、Gitとエージェント以外に必要なものがなくなるため、移行が容易になります。

以下は5つのステップからなるシンプルなワークフローです。

1. タスクの説明。 実装する必要がある変更または機能の短い説明を記述します。
2. 要件の分析。 エージェントはタスクを読み取り、関連するコードとドキュメントを調べます。
3. 実装計画の作成。 エージェントは提案されたソリューションを追加し、行う予定の変更を特定します。
4. レビューと承認。 開発者が計画をレビューし、実装を承認します。
5. 実装と報告。 エージェントはコードを変更し、必要に応じてドキュメントを更新し、実装レポートをタスクファイルに追加します。

タスクの説明、実装計画、およびレポートは1つのファイルにまとめられます。これにより、元の要件をレビューし、計画されたアプローチを理解し、エージェントが実際に行った変更を確認することが容易になります。

承認ステップにより、人間が管理下に置かれます。エージェントはタスクの説明から実装へ直接進むわけではありません。計画は最初にレビューおよび修正できます。

セットアップ例

私のセットアップでは、3つの別々のGitリポジトリを使用しています。

• コード
• ドキュメント
• タスク

ドキュメントとタスクは、しばしば異なるアクセス要件を持ちます。ドキュメントは公開される可能性がありますが、タスクには、未完了のセキュリティ修正、内部計画、またはまだ発表されていない機能に関する機密情報が含まれる場合があります。別々のリポジトリを使用すると、アクセスを個別に設定し、タスクをプライベートに保つことができます。

ローカルでは、開発者はドキュメントリポジトリとタスクリポジトリをコードリポジトリ内のフォルダにクローンします。両方のフォルダはコードリポジトリの .gitignore ファイルにリストされているため、親リポジトリはそれらの内容を追跡しません。各クローンされたリポジトリは、独自のGit履歴を保持し、個別にコミット、プッシュ、同期できます。

/code-repo
  /src
  /tests
  /docs                 # Separate documentation repository
    /user-guides
    /admin-manuals
    /developer-docs
  /tasks                # Separate private task repository
    /release-123
      task-551-something-descriptive.md
      task-552-something-descriptive.md
  .gitignore            # Excludes docs and tasks

すべての情報は、Claude CodeやOpenCodeのようなローカルコーディングアシスタントで利用可能になります。タスクを実装する際、エージェントはタスクを読み取り、コードを分析し、変更を実装し、関連するドキュメントを更新します。実装レポートはタスクとともに保持され、実際のコード変更はコードリポジトリに記録されます。Gitコミットでタスクファイル名を参照すると、実装と元の要件を関連付けるのに役立ちます。

タスクがリリースフォルダに整理されている場合、エージェントは完了したタスクとGit履歴を使用して、変更ログとリリースノートを作成できます。同じ情報が、更新が必要なドキュメントを特定するのに役立ちます。

インターフェースの追加

GitとAIコーディングエージェントがあれば、このワークフローを実行するのに十分です。ブラウザベースのインターフェースは、Gitを基盤となるバージョン管理システムとして置き換えることなく、ファイルを閲覧、編集、整理するための別の方法を追加します。

TypemillはコンテンツをGitリポジトリと同期できます。複数のリポジトリをサポートしているため、ドキュメンテーションプロジェクトとは別にプライベートタスク用の別個のプロジェクトを設定できます。これにより、コンテンツは別々のリポジトリに存在していても、同じインターフェースで両方を管理できます。

Tasks:

［画像: Screenshot Tasks as Code］

Documentation:

［画像: Screenshot of the documentation in Typemill］

同じファイルは3つのインターフェースからアクセスできます。

• IDEで: 開発者とAIエージェントはローカルリポジトリを直接操作します。
• GitHubで: コントリビューターはリポジトリインターフェースを通じて変更をレビューし、ファイルを編集できます。
• ブラウザで: Typemillは、タスクとドキュメントを読み取り管理するためのインターフェースを提供します。

各インターフェースは異なる目的を果たします。IDEは実装をサポートし、GitHubはリポジトリレベルのコラボレーションを提供し、CMSはテクニカルユーザーでないプロダクトオーナーやテクニカルライター向けのコンテンツインターフェースと公開プラットフォームを提供します。Gitはバージョン履歴と同期を担当します。

このセットアップは、重要な区別を示しています。インターフェースがデータを所有する必要はありません。それは、他のツールからポータブルでアクセス可能なままであるファイルで作業するための便利な方法を提供します。

ローカル、プライベート、ファイルベース

TypemillとフラットファイルCMSは、このワークフローを試すための迅速なオプションの1つにすぎません。MarkdownファイルをGitに保持し、エージェントにそれらへのアクセスを許可するあらゆるセットアップが機能し、タスクファイルのフォルダ以外は何もなく始めることができます。

より興味深い質問は、次に何が起こるかです。タスクがドキュメンテーションに続いてリポジトリに入ると、このモデルのために設計された新しいソフトウェアとインターフェースが登場するでしょう。開発者、プロダクトオーナー、テクニカルライターは、作業するための共有スペースを必要とし、エージェントはそのワークフローの一部となるでしょう。現在のチケットシステムのどの機能がまだ必要とされるかというオープンな質問もあります。割り当て、コメント、カンバンボード、スプリント？エージェントがほとんどの作業を行う場合、おそらくすべてが必要なわけではありません。

上記のセットアップに基づくと、私が探すプロパティは次のとおりです。

• Gitネイティブ: タスクと仕様は、Gitで管理され、コードやドキュメントに接続された読み取り可能なファイルです。
• ドキュメントとタスクを一緒に: 1つのインターフェースがドキュメントとタスク管理の両方にアクセスを提供します。
• ファイルベース: Markdownは、特定のプラットフォームに依存せず、読み取り可能でポータブルなままです。
• セルフホスト: チームはデータ、プライバシー、インフラストラクチャを管理下に置きます。
• AIサービスに対応: 開発者は好みのAIプロバイダーを選択でき、インターフェースは単一のサービスにユーザーをロックインするのではなく、汎用的な統合を提供する必要があります。

---