agent-bot/takt
1
0
Fork 0
Code Issues 1 Pull Requests Actions Packages Projects Releases Wiki Activity
takt/builtins/ja/INSTRUCTION_STYLE_GUIDE.md
nrslib ea7ce54912 takt: # タスク指示書: resources/ → builtins/ リネーム + export-cc 修正 
## 概要
`resources/` ディレクトリを `builtins/` にリネームし、用途を明確化。同時に export-cc コマンドを拡張して全リソースをコピーするように修正する。

---

## タスク一覧

### 1. ディレクトリリネーム（優先度: 高）

| 変更前 | 変更後 |
|--------|--------|
| `resources/` | `builtins/` |
| `resources/global/{lang}/` | `builtins/{lang}/`（global/ 階層を除去） |
| `resources/project/` | `builtins/project/` |
| `resources/skill/` | `builtins/skill/` |

### 2. 不要ファイル削除（優先度: 高）

- `builtins/{lang}/prompts/` を削除
  - 対象: `interactive-system.md`, `interactive-summary.md`
  - 理由: コードから未参照、実体は `src/shared/prompts/`

### 3. コード修正 — パス参照（優先度: 高）

`resources` → `builtins`、`global/{lang}` → `{lang}` に更新:

| ファイル | 修正内容 |
|----------|----------|
| `src/infra/resources/index.ts` | `getResourcesDir()`, `getGlobalResourcesDir()`, `getLanguageResourcesDir()` 等のパス |
| `src/infra/config/paths.ts` | `getBuiltinPiecesDir()`, `getBuiltinPersonasDir()` |
| `src/infra/config/global/initialization.ts` | `copyLanguageConfigYaml()` |
| `src/infra/config/loaders/pieceCategories.ts` | `getLanguageResourcesDir()` 参照 |
| `src/features/config/ejectBuiltin.ts` | `getLanguageResourcesDir()` 参照 |
| `src/features/config/deploySkill.ts` | `getResourcesDir()` 参照 |

### 4. export-cc 修正（優先度: 高）

ファイル: `src/features/config/deploySkill.ts`

**現状**: pieces/ と personas/ のみコピー

**修正後**:
- `builtins/{lang}/` 全体を `~/.claude/skills/takt/` にコピー
- `skill/` のファイル（SKILL.md, references/, takt-command.md）は従来通り
- サマリー表示を新リソースタイプ（stances, instructions, knowledge 等）に対応
- confirm メッセージ修正:
  - 現状: `'上書きしますか？'`
  - 修正後: `'既存のスキルファイルをすべて削除し、最新版に置き換えます。続行しますか？'`

### 5. テスト修正（優先度: 中）

| ファイル | 修正内容 |
|----------|----------|
| `src/__tests__/initialization.test.ts` | `getLanguageResourcesDir` のパス期待値 |
| `src/__tests__/piece-category-config.test.ts` | mock パス |
| その他 `resources` パスを参照しているテスト | パス更新 |

### 6. ビルド・パッケージ設定（優先度: 中）

| ファイル | 修正内容 |
|----------|----------|
| `package.json` | `files` フィールドで `resources/` → `builtins/` |
| `tsconfig.json` | `resources/` への参照があれば更新 |
| `.gitignore` | 必要に応じて更新 |

### 7. ドキュメント（優先度: 低）

- `CLAUDE.md` の Directory Structure セクションを更新
- JSDoc コメントから `prompts/` 記述を削除

---

## 制約

- `builtins/{lang}/` のフラット構造は変更不可（ピースYAML内の相対パス依存）
- eject のセーフティ（skip-if-exists）は変更不要
- export-cc のセーフティ（SKILL.md 存在チェック + confirm）は維持

---

## 確認方法

- `npm run build` が成功すること
- `npm test` が全てパスすること
- `takt init` / `takt eject` / `takt export-cc` が正常動作すること
2026-02-07 14:46:20 +09:00

306 lines
11 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# インストラクション スタイルガイド
このガイドは `instructions/` のファイルを作成・編集する際のルールを定義する。
## テンプレート
`templates/instructions/` にテンプレートファイルを用意している。新規作成時は参照して使う。
| テンプレート | 用途 |
|------------|------|
| `plan.md` | 計画（タスク分析・要件整理） |
| `architect.md` | 設計（アーキテクチャ設計） |
| `implement.md` | 実装（コーディング + レポート埋め込み） |
| `review.md` | レビュー（parallel sub-step 汎用） |
| `ai-review-standalone.md` | AIレビュー（standalone、iteration tracking） |
| `ai-fix.md` | AI指摘修正（全ピース共通） |
| `fix.md` | レビュー指摘修正（汎用 fix / supervise fix） |
| `arbitrate.md` | 裁定（レビュアー vs コーダー） |
| `supervise.md` | 最終検証（レポート埋め込み） |
---
## インストラクションとは
ピースのムーブメントで実行する具体的な手順。`instruction_template` フィールドに直接記述するか、ファイル参照で使用する。
| 項目 | 内容 |
|------|------|
| 目的 | ムーブメントの実行手順と出力要件の定義 |
| 配置 | Phase 1 メッセージの `## Instructions`（`{{instructions}}`） |
| 対象 | 1つのムーブメント |
| 判断基準 | 「この手順は特定のムーブメント/ピースに固有か？」→ YES |
### 実際の配置先
インストラクションは `src/shared/prompts/{lang}/perform_phase1_message.md` の `{{instructions}}` に展開される。
```
## 実行コンテキスト（作業ディレクトリ）
## 実行ルール（git commit禁止、cd禁止、edit権限）
## Piece Context（ピース名、Iteration、Movement Iteration、Report Directory）
## User Request（自動注入）
## Previous Response（自動注入、pass_previous_response: true 時）
## Additional User Inputs（自動注入）
## Instructions
{{instructions}} ← ★ インストラクションがここに展開される
```
インストラクションの前に実行コンテキスト、ピース情報、ユーザーリクエスト、前回レスポンス等が既に提供されている。これらを再記述する必要はない。
### ペルソナ・スタンスとの分離
```
この内容は…
├── エージェントの identity・専門知識 → ペルソナ
├── 複数エージェントの共有ルール → スタンス
└── ムーブメント固有の手順・出力形式 → インストラクション
```
---
## エンジンの自動注入
2つのメカニズムがある。いずれもインストラクション内に手動で記述する必要はない。
### セクション注入（`## Instructions` の前に別セクションとして挿入）
`perform_phase1_message.md` のテンプレート側で処理される。instruction_template の外に配置される。
| セクション | 内容 | デフォルト |
|-----------|------|-----------|
| `## User Request` | ユーザーの元リクエスト | **常に表示** |
| `## Previous Response` | 前ムーブメントの出力 | **初回以外は常に表示**（`pass_previous_response` デフォルト: `true`） |
| `## Additional User Inputs` | 蓄積されたユーザー入力 | **常に表示** |
抑制したい場合は instruction_template 内にプレースホルダー（`{task}`, `{previous_response}`, `{user_inputs}`）を含めるか、`pass_previous_response: false` を設定する。通常は不要。
### テンプレート変数展開（instruction_template 内のプレースホルダーを置換）
InstructionBuilder が instruction_template 内の `{変数名}` を展開する。インストラクション内で使用可能。
| 変数 | 内容 |
|------|------|
| `{iteration}` | ピース全体のイテレーション数 |
| `{max_iterations}` | 最大イテレーション数 |
| `{movement_iteration}` | ムーブメント単位のイテレーション数 |
| `{report_dir}` | レポートディレクトリ名 |
| `{report:filename}` | 指定レポートの内容展開（ファイルが存在する場合） |
| `{cycle_count}` | ループモニターで検出されたサイクル回数（`loop_monitors` 専用） |
また、タグベースのルールがある場合は `[STEP:N]` タグの出力ルールが末尾に自動付加される。
---
## 書き方ルール
### 構造パターン
インストラクションは以下の構造に従う。すべてのセクションが必須ではない。
```
1. 目的の宣言（1-2行）
2. 注意事項・条件（該当する場合）
3. やること（手順 or 観点）
4. レポートフォーマット（埋め込みの場合）
5. 必須出力（見出しを含める）
```
### 目的の宣言
- 冒頭1-2行で何をすべきかを簡潔に記述
- 命令形（「〜してください。」）を使用
```markdown
# 良い例
タスクを分析し、実装方針を立ててください。
# 良い例
テスト実行、ビルド確認、最終承認を行ってください。
# 悪い例
このムーブメントではタスクの分析を行います。 ← 説明文になっている
```
### 注意事項・条件
- 差し戻し、イテレーション回数、前提条件がある場合に記述
- `**注意:**` または `**重要:**` の太字ラベルで強調
```markdown
# 良い例
**注意:** Previous Responseがある場合は差し戻しのため、
その内容を踏まえて計画を見直してください（replan）。
# 良い例（イテレーション追跡）
**これは {movement_iteration} 回目の AI Review です。**
2回目以降は、前回の修正が実際には行われていなかったということです。
```
### やること
- 番号付きリストまたは箇条書きで手順/観点を列挙
- レビュー系は「レビュー観点」としてまとめる
```markdown
# 実行系（番号付きリスト）
**やること:**
1. タスクの要件を理解する
2. 影響範囲を特定する
3. 実装アプローチを決める
# レビュー系（箇条書き）
**レビュー観点:**
- 構造・設計の妥当性
- コード品質
- テストカバレッジ
```
### レポートフォーマット埋め込み
- インストラクション内にレポートフォーマットを埋め込む場合がある
- コードブロック（```markdown）で囲む
- ラベル（`**Scopeレポートフォーマット:**` 等）を付ける
```markdown
# 良い例
**Scopeレポートフォーマット（実装開始時に作成）:**
\`\`\`markdown
# 変更スコープ宣言
...
\`\`\`
```
### 必須出力
- `**必須出力（見出しを含める）**` の見出しで出力要件を定義
- 見出しは `##` で指定（エージェントの出力にそのまま使われる）
- `- {プレースホルダー}` で各項目の説明
```markdown
**必須出力（見出しを含める）**
## 作業結果
- {実施内容の要約}
## 変更内容
- {変更内容の要約}
## テスト結果
- {実行コマンドと結果}
```
---
## DO / DON'T
| DO | DON'T |
|----|-------|
| 目的を冒頭1-2行で命令形で書く | 長い説明文で始める |
| 手順を番号付きリストで列挙 | 曖昧な指示を出す |
| テンプレート変数を正しく使う | 自動注入される変数を手動で書く |
| レポートフォーマットは```markdownで囲む | プレーンテキストでフォーマットを書く |
| 必須出力の見出しを `##` で指定 | 出力形式を指定しない |
| そのムーブメントの手順に集中 | ペルソナ（専門知識）の内容を混ぜる |
| `{report:filename}` でレポートを参照 | ファイルパスをハードコードする |
---
## インストラクションに書いてはいけないもの
1. **ペルソナの内容**: エージェントの専門知識、検出手法、行動姿勢
2. **スタンスの内容**: DRY、Fail Fast 等の共有コーディング原則
3. **自動注入される内容**: `{task}`, `{previous_response}` のプレースホルダーを明示的に書かない（エンジンが自動付加する）
4. **他のムーブメント名の直接参照**: 「implement ムーブメントに戻る」等（ルーティングはルール定義の責務）
5. **ピース固有のルーティング**: 「APPROVE なら次へ」等（ルール条件の責務）
### 例外: レポート参照
`{report:filename}` を使ったレポート内容の展開は許容する。これはピース固有の概念だが、インストラクションの中核機能。
```markdown
# 許容
**参照するレポート:**
- AIレビュー結果: {report:ai-review.md}
# 非許容
**参照するレポート:**
- .takt/reports/20250101-task/ai-review.md ← パスのハードコード
```
---
## カテゴリ別パターン
### 計画系（plan, plan-investigate, architect）
- 目的宣言 + やること（番号付き） + replan 注意事項
- レポートフォーマット埋め込みなし（レポートは report-formats/ に分離）
- 5-20行
### 実装系（implement）
- 目的宣言 + テスト要件 + Scope/Decisions レポート埋め込み + 必須出力
- レポートフォーマットを2つ埋め込む（Scope + Decisions）
- 30-50行
### レビュー系（review-*, ai-review）
- 目的宣言 + 「〜はレビューしない」の除外指示 + レビュー観点
- parallel sub-step の場合は短く（5-12行）
- standalone の場合はイテレーション追跡付き
### 修正系（fix, ai-fix, fix-supervisor）
- 修正指示 + 必須出力 + 証拠セクション
- ai-fix は特殊: 「修正済み認識」対策を含む（カスタマイズ不可）
- fix は「セッションの会話履歴を確認」の指示を含む
### 裁定系（arbitrate）
- 状況説明 + レポート参照 + 判断基準
- `{report:filename}` でレビュー結果を展開
### 検証系（supervise）
- 確認項目 + レポート確認指示 + Validation/Summary レポート埋め込み
- 30-55行
---
## 共通ルール
### 文体
- 丁寧語（「〜してください。」）を使用
- ペルソナ・スタンスの常体とは異なる
- エージェントへの指示なので命令調
### ファイル命名
- `{role}.md` または `{role}-{modifier}.md`
- 例: `plan.md`, `plan-investigate.md`, `review-arch.md`
- ハイフン区切り
- 英語小文字のみ
### ファイルサイズ
| 種別 | 目安 | 上限 |
|------|------|------|
| レビュー sub-step | 5-12行 | 20行 |
| 計画・修正 | 10-20行 | 30行 |
| 実装・検証 | 30-50行 | 60行 |
| ai-fix（特殊） | 35-45行 | 50行 |
短いほどよい。冗長な説明は認知負荷を増やす。
---
## チェックリスト
- [ ] 冒頭1-2行で目的が命令形で書かれているか
- [ ] 自動注入される変数（{task}等）を手動で書いていないか
- [ ] ペルソナの内容（専門知識、行動姿勢）が混入していないか
- [ ] スタンスの内容（共有コーディング原則）が混入していないか
- [ ] レポートフォーマット埋め込みが```markdownで囲まれているか
- [ ] 必須出力の見出しが `##` で指定されているか
- [ ] ファイルパスがハードコードされていないか（`{report:filename}` を使う）
- [ ] そのムーブメントの手順に集中しているか（ルーティング指示なし）
Reference in New Issue View Git Blame Copy Permalink