aidev-template Guide

本ガイドでは、aidev-template を活用したプロジェクト構築、開発環境のセットアップ、テンプレート同期スクリプト（sync_template.py）の使い方、および提案書を用いたテンプレートフィードバックの手順を総合的に解説します。

Overview

aidev-template は、AIエージェント（Antigravity, Claude Code, Codex等）と人間が協調して開発を進めるための基本システムおよび各種ガイドラインを提供するプロジェクトテンプレートです。

主な特徴

ハーネスエージェントの提供: .agents/ や .claude/ にエージェント用カスタムスキル、ルール、フック設定を保持。
体系化された開発ドキュメント: docs/ 配下に設計、仕様、タスク、意思決定記録（Decision Records）などの標準フォーマットを用意。
一元化された環境・タスク管理: mise を活用し、開発ツールの管理や実行エントリーポイントを共通化。
テンプレート同期機構: .mise/scripts/sync_template.py を使用し、テンプレート本体の最新アップデートを各個別プロジェクトへ安全に同期。

Setup & Environment

aidev-template を使用するプロジェクトをセットアップするための手順と環境設定を解説します。

1. 動作前提条件

PowerShell 7.x (pwsh): Windows 環境における標準シェル。
Python 3.10 以上: スクリプト実行用。
mise: タスクランナーおよび開発ツールバージョン管理ツール。
Node.js: .agents/hooks/ 配下のフックスクリプト（JavaScript）の実行用。
- フック用依存パッケージ:
  - ignore パッケージ: .agents/hooks/check-read-file.js や .agents/hooks/check-write-file.js で .devai.json（hook.read / hook.write）のアクセス制御判定を行うために必要です。テンプレート本体（AIDEV_TEMPLATE_PATH）側でインストール（npm install ignore）しておくことで、各派生プロジェクトから共有利用されます。
  - markdownlint-cli2 パッケージ: .agents/hooks/lint-markdown.js で Markdown ファイルの自動検証・修正を行うために必要です。テンプレート本体（AIDEV_TEMPLATE_PATH）側でインストール（npm install markdownlint-cli2）しておくことで、各派生プロジェクトから共有利用されます。

2. 環境変数 `AIDEV_TEMPLATE_PATH` の設定

テンプレートの同期・更新機能を利用するには、マスタとなる aidev-template リポジトリの絶対パスを環境変数 AIDEV_TEMPLATE_PATH に設定します。

3. 環境変数 `MDTS_DOCS_PORT` の設定

ドキュメントサーバー起動タスク（mise run aidev:docs）で使用するポート番号を環境変数 MDTS_DOCS_PORT に設定します。

`.env` ファイルでの設定例

プロジェクトルートの .env ファイルに記述することも可能です：

AIDEV_TEMPLATE_PATH=C:/dev/src/aidev-template
MDTS_DOCS_PORT=8521

3.1 環境診断とセットアップ支援 (`setup-aidev`)

開発環境の前提ツールや設定が整っているかを一括で確認・診断するには、以下のタスクを実行します：

mise run aidev:check-env

また、AI エージェントに対して「セットアップを確認して」「環境を診断して」と指示することで、エージェントスキル setup-aidev が起動し、不足項目のガイドや初期設定を自動支援します。

4. ハーネス設定の初期セットアップ

mise タスクを実行して、エージェント設定ファイルおよびフックをローカル環境に配置します：

mise run aidev:setup-antigravity

このコマンドにより、.agents/settings.gemini.json および .agents/statusline.gemini.ps1 がユーザープロファイル配下の設定ディレクトリに自動コピーされます。

また、フックで利用する Node.js パッケージ（ignore, markdownlint-cli2 等）はテンプレート本体（AIDEV_TEMPLATE_PATH）配下にインストールしておく必要があります（各個別プロジェクト側でのインストールは不要です）：

cd $env:AIDEV_TEMPLATE_PATH
npm install ignore markdownlint-cli2

mise run "aidev:sync(dryrun)"

② 同期の実行

テンプレートから最新のファイルを上書き・追加作成します：

mise run aidev:sync

③ 同期スクリプト自体の更新（Self Update）

同期スクリプト本体（.mise/scripts/sync_template.py）も含めて同期を行う場合は、以下のコマンドを使用します：

# ドライラン
mise run "aidev:self-update(dryrun)"

# 同期実行
mise run aidev:self-update

同期処理完了後、同期元となったテンプレートリポジトリのコミットハッシュを含む推奨コミットメッセージが表示されます：

Recommended commit message:
  chore(aidev-template): pull 73dcee8

④ バックアップファイル (.bak) の整理とクリーンアップ

同期の際、既存ファイルが更新（UPDATE）されると、旧ファイルは自動的に filename.bak として同期先に一時退避されます。

内容を確認し、不要になったバックアップファイルは以下のタスクで安全に一括削除できます（同期対象外の無関係な .bak ファイルには影響しません）：

# 事前確認 (ドライラン)
mise run "aidev:clean-bak(dryrun)"

# 対象の .bak ファイルを一括削除
mise run aidev:clean-bak

Proposal & Feedback Workflow

プロジェクト運用中に得られた知見やディレクトリ構造の拡張案などを、aidev-template 本体へ安全に取り込むための提案書（Proposal）によるフィードバック手順です。

※ 提案書はエージェントスキル write-proposal（または同スキル内のテンプレート構造）を利用して作成します。

flowchart TD
    A["1. 提案書の作成<br>(<workspace>/<topic>-proposal.md)"] --> B["2. AIエージェントへ取り込み指示<br>(topic: フィードバックを取り込みます...)"]
    B --> C["3. 変更案(Diff)の表示とユーザー確認"]
    C --> D["4. ドキュメント・設定への反映"]
    D --> E["5. テンプレート本体へコミット・同期"]

1. 提案書の作成場所と命名規則

作成領域: ワークスペースディレクトリ内（<workspace>）
ファイル名: <topic>-proposal.md（例: aidev-template-proposal.md, directory-structure-proposal.md）

2. 提案書の基本構造（テンプレート）

提案書は以下のフォーマットで作成します：

---
name: <topic>-proposal
title: "<提案のタイトル>"
description: "<提案内容の概要サマリー>"
timestamp: YYYY-MM-DD
ai: ai-coauthored
---

# <提案のタイトル>

## 1. 提案の背景と目的

現在の構成における課題や、拡張・変更を行う目的を記述します。

## 2. 拡張提案の詳細

具体的な変更仕様や新設するディレクトリ・機能のルールを定義します。

## 3. ドキュメントへの変更案 (Diff)

修正対象ドキュメントに対する具体差分案を記述します。

```diff
--- docs/guide/target-document.md
+++ docs/guide/target-document.md
@@ -10,3 +10,5 @@
 現状の記述
+追加する記述
```

## 4. 期待される効果

本変更によって得られる保守性や開発効率向上のメリットを整理します。

3. AIエージェントへのフィードバック指示手順

提案書を作成後、AIエージェントに対して以下の指示を送ります：

topic: フィードバックを取り込みます。詳細は <workspace> にある提案書を確認してください

エージェントは提案書を読み込み、事前確認用の Diff を提示した上で、指定のドキュメントやスクリプトを自動更新します。

directory-structure.md: プロジェクトの標準ディレクトリ構成および役割定義
document-development-guide.md: 開発プロセスおよびドキュメント展開ガイド
commit-message.md: Conventional Commits に準拠したコミットメッセージ規約