170 lines
4.5 KiB
Markdown
170 lines
4.5 KiB
Markdown
# ポリシー スタイルガイド
|
||
|
||
このガイドは `policies/` のファイルを作成・編集する際のルールを定義する。
|
||
|
||
## テンプレート
|
||
|
||
`templates/policies/` にテンプレートファイルを用意している。新規作成時はコピーして使う。
|
||
|
||
| テンプレート | 用途 | 使用例 |
|
||
|------------|------|--------|
|
||
| `policy.md` | 共有行動規範 | coding, review, testing |
|
||
|
||
---
|
||
|
||
## ポリシーとは
|
||
|
||
複数のエージェントが共有する行動規範。user message（instruction 内）に配置される。
|
||
|
||
| 項目 | 内容 |
|
||
|------|------|
|
||
| 目的 | 複数エージェントが共有する行動規範 |
|
||
| 配置 | user message（instruction 内） |
|
||
| 対象 | 複数のエージェント |
|
||
| 判断基準 | 「複数のエージェントが同じルールに従うか？」→ YES ならポリシー |
|
||
|
||
### ペルソナとの分離
|
||
|
||
```
|
||
このルール/知識は…
|
||
├── 特定のエージェントだけが必要 → ペルソナ（ドメイン知識）
|
||
├── 複数のエージェントが共有 → ポリシー
|
||
└── 特定のピースの実行手順 → instruction_template（ポリシーに書かない）
|
||
```
|
||
|
||
---
|
||
|
||
## フォーマット
|
||
|
||
```markdown
|
||
# {ポリシー名}
|
||
|
||
{1文の目的説明。「〜する。」で終わる}
|
||
|
||
## 原則
|
||
|
||
| 原則 | 基準 |
|
||
|------|------|
|
||
| ... | ... |
|
||
|
||
## {ルールカテゴリ1}
|
||
|
||
{自由形式: テーブル、コード例、箇条書き}
|
||
|
||
## {ルールカテゴリ2}
|
||
...
|
||
```
|
||
|
||
---
|
||
|
||
## セクション詳細
|
||
|
||
### 目的説明（必須）
|
||
|
||
- 1文でポリシーの目的を宣言
|
||
- 体言止めまたは「〜する。」で終わる
|
||
|
||
```markdown
|
||
# 良い例
|
||
速さより丁寧さ、実装の楽さよりコードの正確さを優先する。
|
||
|
||
# 悪い例
|
||
コーディングに関するルールです。 ← 曖昧
|
||
```
|
||
|
||
### 原則テーブル（必須）
|
||
|
||
- ポリシーの核心を5-10行のテーブルで表現
|
||
- 各行は「原則名 + 1行の基準」
|
||
|
||
### ルールカテゴリ（1つ以上）
|
||
|
||
- `##` で直接カテゴリを作る（`###` を挟まない）
|
||
- テーブル、コード例、箇条書きを自由に使う
|
||
- ネストは `###` まで（`####` は使わない）
|
||
|
||
---
|
||
|
||
## DO / DON'T
|
||
|
||
| DO | DON'T |
|
||
|----|-------|
|
||
| 複数エージェントに共通するルールを記載 | 特定エージェントにしか適用されない知識を含める |
|
||
| コード例で「良い例/悪い例」を示す | 抽象的な原則だけ列挙する |
|
||
| 目的説明は1文で簡潔に | 長い説明文を書く |
|
||
| `##` でカテゴリを直接分ける | `####` 以下のネストを使う |
|
||
|
||
---
|
||
|
||
## ポリシーに書いてはいけないもの
|
||
|
||
1. **特定エージェント固有の知識**: Architecture Reviewer だけが使う検出手法等
|
||
2. **ピース固有の概念**: ムーブメント名、レポートファイル名
|
||
3. **ツール固有のパス**: `.takt/runs/` 等の具体的なディレクトリパス
|
||
4. **実行手順**: どのファイルを読め、何を実行しろ等
|
||
|
||
---
|
||
|
||
## 共通ルール
|
||
|
||
### 見出しの深さ
|
||
|
||
最大 `###` まで。`####` 以下は使わない。深くなる場合は構造を見直す。
|
||
|
||
### コード例
|
||
|
||
- 「良い例/悪い例」のペアで示す
|
||
- コメントで `// REJECT` `// OK` `// APPROVE` を付ける
|
||
- 言語は対象プロジェクトに合わせる（TypeScript が主）
|
||
|
||
```typescript
|
||
// REJECT - 問題の簡潔な説明
|
||
const bad = ...
|
||
|
||
// OK - 正しい理由の簡潔な説明
|
||
const good = ...
|
||
```
|
||
|
||
### テーブル
|
||
|
||
判定基準テーブルは「基準 → 判定」の形式で統一する。
|
||
|
||
```markdown
|
||
| 基準 | 判定 |
|
||
|------|------|
|
||
| 条件A | REJECT |
|
||
| 条件B | 警告 |
|
||
| 条件C | OK |
|
||
```
|
||
|
||
### 文体
|
||
|
||
- 体言止めまたは「〜する」の常体
|
||
- 丁寧語（です・ます）は使わない
|
||
- 簡潔に。冗長な説明は避ける
|
||
|
||
### ファイル命名
|
||
|
||
- `{category}.md`（例: `coding.md`, `review.md`, `testing.md`）
|
||
- ハイフン区切り（スネークケース不可）
|
||
- 英語小文字のみ
|
||
- ディレクトリでグルーピングしない（フラット構造）
|
||
|
||
### ファイルサイズ
|
||
|
||
| 目安 | 上限 |
|
||
|------|------|
|
||
| 60-250行 | 300行 |
|
||
|
||
---
|
||
|
||
## チェックリスト
|
||
|
||
- [ ] 目的説明が1文で書かれているか
|
||
- [ ] 原則テーブルがあるか
|
||
- [ ] 複数のエージェントに適用可能な内容か
|
||
- [ ] 特定エージェント固有の知識が混入していないか
|
||
- [ ] ピース固有の概念が含まれていないか
|
||
- [ ] ツール固有のパスが含まれていないか
|
||
- [ ] `####` 以下のネストがないか
|