agent-bot/takt
1
0
Fork 0
Code Issues 1 Pull Requests Actions Packages Projects Releases Wiki Activity
takt/builtins/ja/REPORT_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

274 lines
9.1 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.

# レポートフォーマット スタイルガイド
このガイドは `report-formats/` のファイルを作成・編集する際のルールを定義する。
## テンプレート
`templates/reports/` にテンプレートファイルを用意している。新規作成時は参照して使う。
| テンプレート | 用途 |
|------------|------|
| `plan.md` | タスク計画（標準 / 拡張） |
| `architecture-design.md` | アーキテクチャ設計 |
| `review.md` | 汎用レビュー結果 |
| `security-review.md` | セキュリティレビュー（重大度付き） |
| `validation.md` | 最終検証結果 |
| `summary.md` | タスク完了サマリー |
---
## レポートフォーマットとは
エージェントが出力するレポートの構造定義。ピースYAMLの `report.format` フィールドで使用する。
| 項目 | 内容 |
|------|------|
| 目的 | エージェント出力の構造を統一し、後続ムーブメントで機械的に参照可能にする |
| 配置 | Phase 2 メッセージの `## Instructions` 内（`{{reportFormat}}`） |
| 対象 | 1つのレポートファイル |
| 判断基準 | 「この出力は後続ムーブメントが `{report:filename}` で参照するか？」→ YES |
### 実際の配置先
レポートフォーマットは `src/shared/prompts/{lang}/perform_phase2_message.md` の `{{reportFormat}}` に展開される。
```
## 実行コンテキスト（作業ディレクトリ）
## 実行ルール（ソース変更禁止、レポートのみ）
## Piece Context
## Instructions
"レポートとして回答してください。ツールは使えません。"
{{reportFormat}} ← ★ レポートフォーマットがここに展開される
```
Phase 2 はツール使用不可。エージェントは Phase 1 のセッションを引き継いだ上で、テキスト出力のみでレポートを作成する。
### インストラクションとの違い
| | インストラクション | レポートフォーマット |
|--|-------------------|-------------------|
| 目的 | 何をすべきかの手順 | 出力の構造定義 |
| 配置 | Phase 1 `{{instructions}}` | Phase 2 `{{reportFormat}}` |
| 読者 | エージェント（実行時） | 後続ムーブメントのエージェント（参照時） |
| 形式 | 自由文 + 箇条書き | ```markdown コードブロック |
---
## 書き方ルール
### 全体構造
レポートフォーマットは以下の構造を持つ。
```
1. ```markdown コードブロック（フォーマット本体）
2. 認知負荷軽減ルール（該当する場合）
```
### フォーマット本体
必ず ` ```markdown ` コードブロックで囲む。
```markdown
\`\`\`markdown
# レポートタイトル
## 結果: APPROVE / REJECT
## サマリー
{1-2文で結果を要約}
## 詳細
...
\`\`\`
```
### プレースホルダー
- `{波括弧}` でプレースホルダーを記述
- エージェントが実行時に埋める内容の説明を簡潔に
```markdown
# 良い例
{1-2文で結果を要約}
{タスクの1行要約}
{影響するモジュールや機能}
# 悪い例
{ここにサマリーを記述してください。サマリーは1-2文で簡潔に書いてください。} ← 冗長
```
### 結果ステータス
レビュー系レポートは結果ステータスを持つ。使用するステータスを `/` で列挙する。
| パターン | 用途 |
|---------|------|
| `APPROVE / REJECT` | 二値判定（AI Review、Security Review 等） |
| `APPROVE / IMPROVE / REJECT` | 三値判定（Architecture Review 等） |
| `完了` | 固定値（Summary 等） |
### テーブル
構造化データはテーブルで記述する。
```markdown
# 検証テーブル（チェックリスト形式）
| 観点 | 結果 | 備考 |
|------|------|------|
| 仮定の妥当性 | ✅ | - |
# 問題テーブル（番号付き）
| # | カテゴリ | 場所 | 問題 |
|---|---------|------|------|
| 1 | 幻覚API | `src/file.ts:23` | 存在しないメソッド |
# ファイルテーブル
| 種別 | ファイル | 概要 |
|------|---------|------|
| 作成 | `src/file.ts` | 概要説明 |
```
テーブルの頻出カラム:
| カラム | 使い方 |
|--------|--------|
| `#` | 連番 |
| `スコープ` | 「スコープ内」/「スコープ外」 |
| `場所` | `` `src/file.ts:42` `` 形式 |
| `結果` | ✅ / ❌ |
| `重大度` | High / Medium / Low |
| `種別` | 作成 / 変更 / 削除 |
### 認知負荷軽減ルール
レビュー系レポートには認知負荷軽減ルールを付加する。フォーマット本体の ` ``` ` の後に記述する。
```markdown
**認知負荷軽減ルール:**
- APPROVE → サマリーのみ（5行以内）
- REJECT → 問題点を表形式で（30行以内）
```
目的: 問題がない場合に冗長な出力を抑制する。後続ムーブメントの入力コストを下げる。
---
## DO / DON'T
| DO | DON'T |
|----|-------|
| ```markdown コードブロックで囲む | プレーンテキストでフォーマットを書く |
| プレースホルダーは `{簡潔な説明}` | 冗長な説明をプレースホルダーに入れる |
| テーブルで構造化データを表現 | 箇条書きの入れ子で複雑な構造を表現 |
| 認知負荷軽減ルールで出力量を制御 | APPROVE でも REJECT と同量の出力を求める |
| ステータスの選択肢を明示（APPROVE / REJECT） | ステータスの定義を曖昧にする |
| 場所は `` `file:line` `` 形式 | 自然言語で場所を説明する |
---
## レポートフォーマットに書いてはいけないもの
1. **実行手順**: 「まず〜を確認し」等の手順はインストラクションの責務
2. **判断基準の詳細**: 「何をもって REJECT とするか」はペルソナまたはインストラクションの責務
3. **ピース固有のルーティング**: 「REJECT の場合は fix ムーブメントへ」等
---
## カテゴリ別パターン
### 計画系（plan, architecture-design）
- 結果ステータスなし
- セクション構造: 元の要求 → 分析結果 → 実装ガイドライン
- テーブル: ファイル構成
```markdown
# タスク計画
## 元の要求
## 分析結果
### 目的 / スコープ / 実装アプローチ
## 確認事項
```
### レビュー系（ai-review, architecture-review, qa-review, security-review, frontend-review, cqrs-es-review）
- 結果ステータス: APPROVE / REJECT（または APPROVE / IMPROVE / REJECT）
- セクション構造: 結果 → サマリー → 検証テーブル → 問題テーブル
- 認知負荷軽減ルール付き
```markdown
# {種別}レビュー
## 結果: APPROVE / REJECT
## サマリー
## 確認した観点（テーブル）
## 問題点（REJECTの場合）（テーブル）
```
### レビュー統合系（review-summary）
- 複数レビューの結果を1つにまとめる
- セクション構造: 総合判定 → 個別結果テーブル → 要注意の問題 → 改善提案
### コーダー出力系（coder-scope, coder-decisions）
- 結果ステータスなし
- 実装前（scope）と実装後（decisions）のペア
- コンパクト: 10-20行
### 検証系（validation）
- 結果ステータス: APPROVE / REJECT
- セクション構造: 結果 → 検証サマリーテーブル → 成果物 → 未完了項目
- ビルド・テストの確認方法を含む
### サマリー系（summary）
- 結果ステータス: 固定値「完了」
- セクション構造: タスク → 結果 → 変更内容テーブル → 確認コマンド
- ピースの最終出力として使用
---
## 共通ルール
### 文体
- プレースホルダー以外はそのまま出力される見出し・ラベル
- 常体（「〜する」）
- 簡潔に
### ファイル命名
- `{role}.md` または `{role}-{modifier}.md`
- 例: `plan.md`, `ai-review.md`, `coder-scope.md`
- ハイフン区切り
- 英語小文字のみ
- 番号プレフィックスを付けない（`01-plan.md` ではなく `plan.md`）
番号プレフィックスはピース構造に依存するため、共有ファイルでは使用しない。番号はピースYAMLの `report.name` フィールドで付ける。
### ファイルサイズ
| 種別 | 目安 | 上限 |
|------|------|------|
| コーダー出力 | 10-20行 | 25行 |
| レビュー | 15-25行 | 30行 |
| 検証・サマリー | 15-25行 | 30行 |
| 計画・設計 | 15-25行 | 30行 |
認知負荷軽減ルールを含む場合は +3-5行。
---
## チェックリスト
- [ ] フォーマット本体が ```markdown コードブロックで囲まれているか
- [ ] プレースホルダーが `{簡潔な説明}` 形式か
- [ ] レビュー系は結果ステータス（APPROVE / REJECT 等）が明示されているか
- [ ] テーブルの場所カラムが `` `file:line` `` 形式か
- [ ] 認知負荷軽減ルールが付加されているか（レビュー系）
- [ ] 番号プレフィックスを付けていないか（ファイル名）
- [ ] 実行手順が混入していないか（インストラクションの責務）
- [ ] 30行以内に収まっているか（認知負荷軽減ルール除く）
Reference in New Issue View Git Blame Copy Permalink