agent-bot/takt
1
0
Fork 0
Code Issues 1 Pull Requests Actions Packages Projects Releases Wiki Activity
takt/builtins/ja/KNOWLEDGE_STYLE_GUIDE.md
nrslib 27d650fa10 knowledge のスタイルガイド作成
2026-02-17 08:45:06 +09:00

9.8 KiB
Raw Blame History

ナレッジ スタイルガイド

このガイドは knowledge/ のファイルを作成・編集する際のルールを定義する。

テンプレート

templates/knowledge/ にテンプレートファイルを用意している。新規作成時はコピーして使う。

テンプレート 用途 使用例
knowledge.md ドメイン知識 frontend, backend, security

ナレッジとは

エージェントがレビュー・実装・計画時に参照するドメイン知識。ポリシー（行動規範）やインストラクション（実行手順）とは異なり、「何を知っているべきか」を定義する。

項目 内容
目的 エージェントにドメイン固有の専門知識を与える
配置 user message（instruction 内）
対象 特定ドメインに関わるエージェント全般
判断基準 「これはルールか、知識か？」→ 知識ならナレッジ

実際の配置先

ナレッジは instruction 内に展開され、ポリシーと同じ Phase 1 メッセージに含まれる。

User Message (Phase 1):
  [実行コンテキスト]
  [Piece Context]
  [User Request]
  [Previous Response]
  [Instructions]
    └── [ポリシー]      ← 共有行動規範
    └── [ナレッジ]      ← ★ ドメイン知識がここに展開される

ポリシーが「どう振る舞うべきか」を定義するのに対し、ナレッジは「何を知っているべきか」を提供する。同じ配置先だが役割が異なる。

ポリシーとの分離

この内容は…
├── 「〜すべき」「〜してはいけない」→ ポリシー（行動規範）
├── 「〜はこう動く」「〜の構造はこう」→ ナレッジ（ドメイン知識）
└── 「〜を実行しろ」→ インストラクション（手順）

ナレッジにはドメイン固有の評価基準（| 基準 | 判定 | テーブル）を含めてよい。ポリシーの「行動規範」とナレッジの「評価基準」の違いは次の通り。

ポリシー ナレッジ
性質 横断的ルール ドメイン固有の知識
例 「1テスト1概念」「DRY」 「God Component は REJECT」「Props Drilling は REJECT」
適用範囲 全エージェント共通 特定ドメイン（frontend 等）のエージェント

抽象度の原則

ナレッジは特定のツール・言語・フレームワークに依存せず、パターンや原則として記述する。コード例は具体的なツール/言語で示してよい。

# ✅ 良い例: 原則 → 例示
テスト環境がグローバル状態（DOM等）に依存する場合、プロセスレベルの分離が必要。

| 環境 | 推奨 |
|------|------|
| DOM依存あり | プロセス分離 |
| 純粋ロジック | スレッド分離で十分 |

vitest の場合:
pool: 'forks'（DOM依存）/ pool: 'threads'（純粋ロジック）

# ❌ 悪い例: ツール固有の設定羅列
vitest.config.ts に以下を設定する:
pool: 'forks'
singleFork: true
teardownTimeout: 5000
forceExit: true

セクション詳細

トピック概要（必須）

  • 各 ## トピックの冒頭1-2文で概要を記述
  • 体言止めまたは「〜する」で終わる
# 良い例
## コンポーネント設計

1ファイルにベタ書きしない。必ずコンポーネント分割する。

# 悪い例
## コンポーネント設計

コンポーネントについて説明します。  ← 丁寧語 + 情報がない

評価基準テーブル（推奨）

  • トピックごとに「基準 → 判定」テーブルを置く
  • 判定は OK / 警告 / REJECT / 分離を検討 等
  • そのドメイン固有の品質基準を具体的に
| 基準 | 判定 |
|------|------|
| 1コンポーネント200行超 | 分割を検討 |
| 1コンポーネント300行超 | REJECT |
| 複数の責務を持つコンポーネント | REJECT |

コード例（推奨）

  • 「良い例/悪い例」のペアで示す
  • コメントで // NG // OK を付ける
  • 原則を先に述べ、コード例は例示として配置する
  • 言語は対象プロジェクトに合わせる（TypeScript が主）
# 良い例: 原則 → コード例
子コンポーネントは自身で状態を変更しない。イベントを親にバブリングし、親が状態を操作する。

// NG - 子が自分で状態を変更
const ChildBad = ({ initialValue }) => {
  const [value, setValue] = useState(initialValue)
  ...
}

// OK - 親が状態を管理、子はコールバックで通知
const ChildGood = ({ value, onChange }) => {
  return <input value={value} onChange={e => onChange(e.target.value)} />
}

選択基準テーブル（該当する場合）

  • 複数の選択肢がある場合、判断基準をテーブルで示す
  • 特定の1つを正解としない。条件に応じた使い分けを示す
| 状態の性質 | 推奨配置 |
|-----------|---------|
| UIの一時的な状態 | ローカル（useState） |
| 複数コンポーネントで共有 | Context or 状態管理ライブラリ |
| サーバーデータのキャッシュ | データフェッチライブラリ |

フォーマット

# {ドメイン名}知識

## {トピック1}

{トピックの概要。1-2文}

| 基準 | 判定 |
|------|------|
| ... | ... |

### {サブトピック}

{詳細な説明}

{コード例}

## {トピック2}
...

DO / DON'T

DO DON'T
パターンや原則を抽象的に記述する 特定ツールの設定値をそのまま列挙する
コード例は具体的なツール/言語で示す 本文を特定ツール前提で書く
ドメイン固有の評価基準をテーブルで示す 横断的なルール（DRY等）を書く（→ ポリシー）
選択肢がある場合は判断基準をテーブルで示す 1つのツールだけを正解として提示する
「なぜそうすべきか」の理由を書く 設定のコピペだけで終わる

ナレッジに書いてはいけないもの

  1. 横断的な行動規範: DRY、Fail Fast 等の全エージェント共通ルール → ポリシー
  2. 実行手順: どのファイルを読め、何を実行しろ等 → インストラクション
  3. ピース固有の概念: ムーブメント名、レポートファイル名
  4. ツール固有のパス: .takt/runs/ 等の具体的なディレクトリパス

例外: ドメイン固有の評価基準

ポリシーの REJECT 判定と表面的に似ていても、特定ドメインの品質基準として記載する場合は許容する。

# 許容 — フロントエンド固有の品質基準
| 基準 | 判定 |
|------|------|
| God Component | REJECT |
| Props Drilling（3階層以上） | 状態管理の導入を検討 |

# 非許容 — 横断的な行動規範（ポリシーの責務）
| 原則 | 基準 |
|------|------|
| 1テスト1概念 | 複数の関心事を1テストに混ぜない |

ドメイン固有の評価基準（「God Component は REJECT」）はナレッジ。横断的な行動規範（「1テスト1概念」）はポリシー。

カテゴリ別パターン

技術スタック系（frontend, backend）

  • レイヤー構造・パッケージ設計から始める
  • 各トピックに評価基準テーブル + コード例
  • 大規模になりやすい（500-800行）
# フロントエンド知識
## 層構造
## コンポーネント設計
## 状態管理
## データ取得
## テストインフラ
## アンチパターン検出

設計パターン系（cqrs-es, architecture）

  • パターンの構造と適用条件を中心に
  • 「いつ使うか / いつ使わないか」の判断基準を重視
  • 中規模（200-500行）

横断関心事系（security）

  • リスクレベル（重大 / 高 / 中 / 低）の評価基準
  • 攻撃パターン → 対策 の構造
  • チェックリスト形式が多い

共通ルール

見出しの深さ

最大 ### まで。#### 以下は使わない。深くなる場合は構造を見直す。

テーブル

判定基準テーブルは「基準 → 判定」の形式で統一する。

| 基準 | 判定 |
|------|------|
| 条件A | REJECT |
| 条件B | 警告 |
| 条件C | OK |

文体

  • 体言止めまたは「〜する」の常体
  • 丁寧語（です・ます）は使わない
  • 簡潔に。冗長な説明は避ける

ファイル命名

  • {domain}.md（例: frontend.md, backend.md, security.md）
  • ハイフン区切り（スネークケース不可）
  • 英語小文字のみ
  • フラット構造（ディレクトリでグルーピングしない）

ファイルサイズ

種別 目安 上限
横断関心事（security 等） 100-200行 300行
設計パターン（cqrs-es 等） 200-500行 600行
技術スタック（frontend 等） 500-700行 800行

チェックリスト

  • 原則やパターンとして抽象的に記述されているか（ツール固有の設定羅列になっていないか）
  • コード例は具体的なツール/言語で示しているか
  • 各トピックに評価基準テーブルがあるか
  • 横断的な行動規範が混入していないか（→ ポリシー）
  • インストラクション（実行手順）が混入していないか
  • ドメイン固有の評価基準とポリシーの境界が明確か
  • #### 以下のネストがないか
  • カテゴリに応じたファイルサイズ目安に収まっているか