Appearance
aidev-template Guide
本ガイドでは、aidev-template を活用したプロジェクト構築、開発環境のセットアップ、テンプレート同期スクリプト（sync_template.py）の使い方、および提案書を用いたテンプレートフィードバックの手順を総合的に解説します。
Overview
aidev-template は、AIエージェント（Antigravity, Claude Code, Codex等）と人間が協調して開発を進めるための基本システムおよび各種ガイドラインを提供するプロジェクトテンプレートです。
主な特徴
ハーネスエージェントの提供:
.agents/や.claude/にエージェント用カスタムスキル、ルール、フック設定を保持。体系化された開発ドキュメント:
docs/配下に設計、仕様、タスク、意思決定記録（Decision Records）などの標準フォーマットを用意。一元化された環境・タスク管理:
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-ignore.jsで.agentignoreや.agentallowのアクセス制御判定を行うために必要です。テンプレート本体（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 ファイルに記述することも可能です：
text
AIDEV_TEMPLATE_PATH=C:/dev/src/aidev-template
MDTS_DOCS_PORT=85214. ハーネス設定の初期セットアップ
mise タスクを実行して、エージェント設定ファイルおよびフックをローカル環境に配置します：
powershell
mise run aidev:setup-antigravityこのコマンドにより、.agents/settings.gemini.json および .agents/statusline.gemini.ps1 がユーザープロファイル配下の設定ディレクトリに自動コピーされます。
また、フックで利用する Node.js パッケージ（ignore, markdownlint-cli2 等）はテンプレート本体（AIDEV_TEMPLATE_PATH）配下にインストールしておく必要があります（各個別プロジェクト側でのインストールは不要です）：
powershell
cd $env:AIDEV_TEMPLATE_PATH
npm install ignore markdownlint-cli2Template Sync (sync_template.py)
テンプレート本体（aidev-template）が更新された際、個別プロジェクトへ最新のスキル、フック、ガイドドキュメント、環境設定を同期するための機能です。
1. 同期対象のディレクトリとファイル
以下のパスが同期処理の対象として定義されています：
.agents/skills/（カスタムスキル群）.agents/agents/（サブエージェント定義群）.agents/hooks/（フック処理スクリプト）.agents/statusline.gemini.ps1.agents/settings.gemini.json.sample.mise/（mise 構成タスク群）docs/（全体設計・開発ガイド・各種マニュアル）GEMINI.md（共通AIルール）GEMINI-ja.md
2. 同期タスクの実行方法
mise に定義された以下のタスクを使用して同期を行います。
① 事前確認（ドライラン）
実際のファイルを変更せずに、変更対象（作成・更新・変更なし）のファイル一覧を確認します：
powershell
mise run "aidev:sync(dryrun)"② 同期の実行
テンプレートから最新のファイルを上書き・追加作成します：
powershell
mise run aidev:sync③ 同期スクリプト自体の更新（Self Update）
同期スクリプト本体（scripts/sync_template.py）も含めて同期を行う場合は、以下のコマンドを使用します：
powershell
# ドライラン
mise run "aidev:self-update(dryrun)"
# 同期実行
mise run aidev:self-update同期処理完了後、同期元となったテンプレートリポジトリのコミットハッシュを含む推奨コミットメッセージが表示されます：
text
Recommended commit message:
chore(aidev-template): pull 73dcee8④ バックアップファイル (.bak) の整理とクリーンアップ
同期の際、既存ファイルが更新（UPDATE）されると、旧ファイルは自動的に filename.bak として同期先に一時退避されます。
内容を確認し、不要になったバックアップファイルは以下のタスクで安全に一括削除できます（同期対象外の無関係な .bak ファイルには影響しません）：
powershell
# 事前確認 (ドライラン)
mise run "aidev:clean-bak(dryrun)"
# 対象の .bak ファイルを一括削除
mise run aidev:clean-bakProposal & Feedback Workflow
プロジェクト運用中に得られた知見やディレクトリ構造の拡張案などを、aidev-template 本体へ安全に取り込むための提案書（Proposal）によるフィードバック手順です。
※ 提案書は proposal-template.md のフォーマットに従って記述します。エージェントスキル write-proposal を利用して自動作成することも可能です。
1. 提案書の作成場所と命名規則
作成領域: ワークスペースディレクトリ内（
<workspace>）ファイル名:
<topic>-proposal.md（例:aidev-template-proposal.md,directory-structure-proposal.md）
2. 提案書の基本構造（テンプレート）
提案書は以下のフォーマットで作成します：
markdown
---
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エージェントに対して以下の指示を送ります：
text
topic: フィードバックを取り込みます。詳細は <workspace> にある提案書を確認してくださいエージェントは提案書を読み込み、事前確認用の Diff を提示した上で、指定のドキュメントやスクリプトを自動更新します。
Related Documents
directory-structure.md: プロジェクトの標準ディレクトリ構成および役割定義
document-development-guide.md: 開発プロセスおよびドキュメント展開ガイド
commit-message.md: Conventional Commits に準拠したコミットメッセージ規約