agents-template
hal40n/agents-template
Claude Code agents / skills / rules template for development projects. Two-layer design: real files in agents-template/, symlinks from .claude/.
Instalação
npx convez-ai hal40n/agents-template1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
README
A tradução para o português deste README ainda está na fila.
開発プロジェクト向け AIエージェント・テンプレート
開発プロジェクトで使う agents / skills / rules / 共通指示 を一元管理するテンプレート。
新規プロジェクト開始時に setup.sh でこのテンプレートをコピー展開し、そのまま開発を始める運用を前提とする。
ディレクトリ構成
agents-template/
├── AGENTS.md ← AIエージェント共通指示(実体)
├── CLAUDE.md → AGENTS.md(symlink。Claude Code が自動で読む)
├── security.md ← セキュリティ指示(実体)
├── setup.sh ← 新規プロジェクトへの展開スクリプト
├── README.md / LICENSE / .gitignore
│
├── .agents/ ← マスター実体(編集はここで行う)
│ ├── agents/ ← サブエージェント定義(5)
│ ├── skills/ ← スキル(5)
│ └── rules/ ← 言語別ルール
│ ├── common/ ← 言語非依存の共通ルール(ベース層)
│ ├── python/
│ ├── typescript/
│ ├── rust/
│ └── tailwind/ ← HTML / Tailwind CSS(design-quality 含む)
│
└── .claude/ ← Claude Code の入口(symlink のみ)
├── agents → ../.agents/agents
├── skills → ../.agents/skills
└── settings.local.json (ローカル状態。gitignore 済み)
設計方針
| 役割 | 場所 |
|---|---|
| 実体ファイル | .agents/ 配下(+ AGENTS.md / security.md) |
| Claude Code への入口 | .claude/(.agents/ への symlink のみ) |
- 編集はすべて
.agents/側で行う。.claude/は触らない CLAUDE.mdはプロジェクト直下に置けば Claude Code が自動で読む(中身はAGENTS.md)rules/はドキュメント参照用。各言語ルールはcommon/を**継承(拡張)**する構造
新規プロジェクトを始める(コピー方式)
setup.sh でテンプレートを展開先ディレクトリへコピーする。
./setup.sh <target-dir> [--force] [--git] [--obsidian <名前|パス>]
| オプション | 説明 |
|---|---|
<target-dir> | 展開先ディレクトリ(無ければ作成) |
--force | 展開先に既に AGENTS.md / .agents/ があっても上書きする |
--git | 展開先が Git リポジトリでなければ git init する |
--obsidian <名前> | Obsidian の調査・要件ノートを docs/ へコピーする(後述) |
展開されるもの: AGENTS.md / CLAUDE.md(symlink) / security.md / .gitignore / .agents/ / .claude/agents・skills(symlink)
展開されないもの: README.md / LICENSE(テンプレート固有)・.git・settings.local.json
例
# まっさらな新規プロジェクト
./setup.sh ~/Products/my-new-project --git
# Obsidian の要件ノートも docs/ に持ち込む
./setup.sh ~/Products/my-new-project --git --obsidian Daken
リモートリポジトリをクローンした場合
クローン済み(空リポジトリ含む)のディレクトリにもそのまま適用できる。既存の .git・既存ファイルは保持され、テンプレートは未追跡ファイルとして追加される。
git clone <url> ~/Products/my-repo
~/Products/agents-template/setup.sh ~/Products/my-repo --obsidian <Obsidianプロジェクト名>
- 既に Git リポジトリのため
git initはスキップされる - 既存の
.gitignoreは上書きせず、Claude Code 用エントリだけを追記する(冪等)
Obsidian 連携(調査・要件の持ち込み)
開発前の調査・要件定義は Obsidian の 200-project/<プロジェクト名>/ に集約している前提。
--obsidian で、そのプロジェクトのノート一式を新規プロジェクトの docs/ へコピーする。
./setup.sh ~/Products/froom-cloud --obsidian FRoomアプリ開発
# → ~/Obsidian/200-project/FRoomアプリ開発/ の中身を froom-cloud/docs/ にコピー
- 名前ではなく任意のパスも指定可:
--obsidian ~/notes/foo - Vault のパスは環境変数で変更可:
OBSIDIAN_PROJECT_ROOT(既定~/Obsidian/200-project) - 存在しない名前を指定すると、利用可能なプロジェクト一覧を表示する
マスターを更新する
cd ~/Products/agents-template
# .agents/ 配下(agents / skills / rules)や AGENTS.md を編集
git diff
コピー方式のため、マスターの更新は既存プロジェクトには自動反映されない(スナップショット運用)。 更新を反映したいプロジェクトでは、
setup.sh --forceで再展開するか、必要なファイルだけ手動で取り込む。
含まれているエージェント
| エージェント | 目的 |
|---|---|
code-reviewer | コード品質・セキュリティ・保守性のレビュー |
tdd-guide | TDDサイクル(RED→GREEN→REFACTOR)の進行 |
security-reviewer | 認証・入力検証・シークレット等の脆弱性検出 |
python-reviewer | Python固有の品質・スタイルレビュー |
refactor-cleaner | デッドコード・未使用インポート等のクリーンアップ |
e2e-runner | E2Eテスト(Playwright)の作成・実行・フレーキー対策 |
含まれているスキル
| スキル | 目的 |
|---|---|
coding-standards | コーディング規約のベースライン |
tdd-workflow | TDDワークフロー(カバレッジ80%以上) |
security-review | セキュリティ機能実装時のチェックリスト |
e2e-testing | Playwright E2Eテスト・Page Object Model・CI連携 |
write-readme | README.md執筆ワークフロー(汎用) |
含まれているルール
.agents/rules/ に言語別ルールを格納。各言語は common/ を拡張し、
coding-style / patterns / security / testing / hooks の5点セットを基本とする。
| ディレクトリ | 対象 |
|---|---|
common/ | 言語非依存の共通ルール(ベース層・10ファイル) |
python/ | Python |
typescript/ | TypeScript / JavaScript |
rust/ | Rust |
tailwind/ | HTML / Tailwind CSS(coding-style / patterns / design-quality) |
新言語の追加は .agents/rules/<language>/ を作り、common/ を拡張する5点セットを置く。
言語別ルールの設計は affaan-m/ECC の rules 構造(common 継承・5点セット・frontmatter
paths:glob)を参考にしている。