diff --git a/CLAUDE.md b/CLAUDE.md index f26a082..f195450 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -371,19 +371,30 @@ Files: `.takt/logs/{sessionId}.jsonl`, with `latest.json` pointer. Legacy `.json **Instruction auto-injection over explicit placeholders.** The instruction builder auto-injects `{task}`, `{previous_response}`, `{user_inputs}`, and status rules. Templates should contain only step-specific instructions, not boilerplate. -**Persona prompts contain only domain knowledge.** Persona prompt files (`builtins/{lang}/personas/*.md`) must contain only domain expertise and behavioral principles — never piece-specific procedures. Piece-specific details (which reports to read, step routing, specific templates with hardcoded step names) belong in the piece YAML's `instruction_template`. This keeps personas reusable across different pieces. +**Faceted prompting: each facet has a dedicated file type.** TAKT assembles agent prompts from 4 facets. Each facet has a distinct role. When adding new rules or knowledge, place content in the correct facet. -What belongs in persona prompts: -- Role definition ("You are a ... specialist") -- Domain expertise, review criteria, judgment standards -- Do / Don't behavioral rules -- Tool usage knowledge (general, not piece-specific) +``` +builtins/{lang}/ + personas/ — WHO: identity, expertise, behavioral habits + policies/ — HOW: judgment criteria, REJECT/APPROVE rules, prohibited patterns + knowledge/ — WHAT TO KNOW: domain patterns, anti-patterns, detailed reasoning with examples + instructions/ — WHAT TO DO NOW: step-specific procedures and checklists +``` -What belongs in piece `instruction_template`: -- Step-specific procedures ("Read these specific reports") -- References to other steps or their outputs -- Specific report file names or formats -- Comment/output templates with hardcoded review type names +| Deciding where to place content | Facet | Example | +|--------------------------------|-------|---------| +| Role definition, AI habit prevention | Persona | "置き換えたコードを残す → 禁止" | +| Actionable REJECT/APPROVE criterion | Policy | "内部実装のパブリックAPIエクスポート → REJECT" | +| Detailed reasoning, REJECT/OK table with examples | Knowledge | "パブリックAPIの公開範囲" section | +| This-step-only procedure or checklist | Instruction | "レビュー観点: 構造・設計の妥当性..." | +| Workflow structure, facet assignment | Piece YAML | `persona: coder`, `policy: coding`, `knowledge: architecture` | + +Key rules: +- Persona files are reusable across pieces. Never include piece-specific procedures (report names, step references) +- Policy REJECT lists are what reviewers enforce. If a criterion is not in the policy REJECT list, reviewers will not catch it — even if knowledge explains the reasoning +- Knowledge provides the WHY behind policy criteria. Knowledge alone does not trigger enforcement +- Instructions are bound to a single piece step. They reference procedures, not principles +- Piece YAML `instruction_template` is for step-specific details (which reports to read, step routing, output templates) **Separation of concerns in piece engine:** - `PieceEngine` - Orchestration, state management, event emission diff --git a/builtins/en/personas/coder.md b/builtins/en/personas/coder.md index 926db8b..f222620 100644 --- a/builtins/en/personas/coder.md +++ b/builtins/en/personas/coder.md @@ -33,4 +33,5 @@ You are the implementer. Focus on implementation, not design decisions. - Making design decisions arbitrarily → Report and ask for guidance - Dismissing reviewer feedback → Prohibited - Adding backward compatibility or legacy support without being asked → Absolutely prohibited +- Leaving replaced code/exports after refactoring → Prohibited (remove unless explicitly told to keep) - Layering workarounds that bypass safety mechanisms on top of a root cause fix → Prohibited diff --git a/builtins/en/policies/coding.md b/builtins/en/policies/coding.md index 7ef4af3..1296a9a 100644 --- a/builtins/en/policies/coding.md +++ b/builtins/en/policies/coding.md @@ -7,7 +7,7 @@ Prioritize correctness over speed, and code accuracy over ease of implementation | Principle | Criteria | |-----------|----------| | Simple > Easy | Prioritize readability over writability | -| DRY | Extract after 3 repetitions | +| DRY | Eliminate essential duplication | | Comments | Why only. Never write What/How | | Function size | One function, one responsibility. ~30 lines | | File size | ~300 lines as a guideline. Be flexible depending on the task | @@ -245,23 +245,19 @@ Request → toInput() → UseCase/Service → Output → Response.from() ## Shared Code Decisions -### Rule of Three - -- 1st occurrence: Write it inline -- 2nd occurrence: Do not extract yet (observe) -- 3rd occurrence: Consider extracting +Eliminate duplication by default. When logic is essentially the same and should be unified, apply DRY. Do not decide mechanically by count. ### Should Be Shared -- Same logic in 3+ places +- Essentially identical logic duplicated - Same style/UI pattern - Same validation logic - Same formatting logic ### Should Not Be Shared -- Similar but subtly different (forced generalization adds complexity) -- Used in only 1-2 places +- Duplication across different domains (e.g., customer validation and admin validation are separate concerns) +- Superficially similar code with different reasons to change - Based on "might need it in the future" predictions ```typescript @@ -289,4 +285,6 @@ function formatPercentage(value: number): string { ... } - **Hardcoded secrets** - **Scattered try-catch** - Centralize error handling at the upper layer - **Unsolicited backward compatibility / legacy support** - Not needed unless explicitly instructed +- **Internal implementation exported from public API** - Only export domain-level functions and types. Do not export infrastructure functions or internal classes +- **Replaced code surviving after refactoring** - Remove replaced code and exports. Do not keep unless explicitly told to - **Workarounds that bypass safety mechanisms** - If the root fix is correct, no additional bypass is needed diff --git a/builtins/en/policies/review.md b/builtins/en/policies/review.md index 4908fec..ea70654 100644 --- a/builtins/en/policies/review.md +++ b/builtins/en/policies/review.md @@ -38,9 +38,11 @@ REJECT without exception if any of the following apply. - Direct mutation of objects/arrays - Swallowed errors (empty catch blocks) - TODO comments (not tracked in an issue) -- Duplicated code in 3+ places (DRY violation) +- Essentially identical logic duplicated (DRY violation) - Method proliferation doing the same thing (should be absorbed by configuration differences) - Specific implementation leaking into generic layers (imports and branching for specific implementations in generic layers) +- Internal implementation exported from public API (infrastructure functions or internal classes exposed publicly) +- Replaced code/exports surviving after refactoring - Missing cross-validation of related fields (invariants of semantically coupled config values left unverified) ### Warning diff --git a/builtins/ja/personas/coder.md b/builtins/ja/personas/coder.md index 45d83e6..ad81de3 100644 --- a/builtins/ja/personas/coder.md +++ b/builtins/ja/personas/coder.md @@ -33,4 +33,5 @@ - 設計判断を勝手にする → 報告して判断を仰ぐ - レビュワーの指摘を軽視する → 禁止 - 後方互換・Legacy 対応を勝手に追加する → 絶対禁止 +- リファクタリングで置き換えたコード・エクスポートを残す → 禁止（明示的に残すよう指示されない限り削除する） - 根本原因を修正した上で安全機構を迂回するワークアラウンドを重ねる → 禁止 diff --git a/builtins/ja/policies/coding.md b/builtins/ja/policies/coding.md index 3ec45f3..dafb098 100644 --- a/builtins/ja/policies/coding.md +++ b/builtins/ja/policies/coding.md @@ -7,7 +7,7 @@ | 原則 | 基準 | |------|------| | Simple > Easy | 書きやすさより読みやすさを優先 | -| DRY | 3回重複したら抽出 | +| DRY | 本質的な重複は排除する | | コメント | Why のみ。What/How は書かない | | 関数サイズ | 1関数1責務。30行目安 | | ファイルサイズ | 目安として300行。タスクに応じて柔軟に | @@ -245,23 +245,19 @@ Request → toInput() → UseCase/Service → Output → Response.from() ## 共通化の判断 -### 3回ルール - -- 1回目: そのまま書く -- 2回目: まだ共通化しない（様子見） -- 3回目: 共通化を検討 +基本的に重複は排除する。本質的に同じロジックであり、まとめるべきと判断したら DRY にする。回数で機械的に判断しない。 ### 共通化すべきもの -- 同じ処理が3箇所以上 +- 本質的に同じロジックの重複 - 同じスタイル/UIパターン - 同じバリデーションロジック - 同じフォーマット処理 ### 共通化すべきでないもの -- 似ているが微妙に違うもの（無理に汎用化すると複雑化） -- 1-2箇所しか使わないもの +- ドメインが異なる重複（例: 顧客用バリデーションと管理者用バリデーションは別物） +- 表面的に似ているが変更理由が異なるコード - 「将来使うかも」という予測に基づくもの ```typescript @@ -289,4 +285,6 @@ function formatPercentage(value: number): string { ... } - **機密情報のハードコーディング** - **各所でのtry-catch** - エラーは上位層で一元処理 - **後方互換・Legacy対応の自発的追加** - 明示的な指示がない限り不要 +- **内部実装のパブリック API エクスポート** - 公開するのはドメイン操作の関数・型のみ。インフラ層の関数や内部クラスをエクスポートしない +- **リファクタリング後の旧コード残存** - 置き換えたコード・エクスポートは削除する。明示的に残すよう指示されない限り残さない - **安全機構を迂回するワークアラウンド** - 根本修正が正しいなら追加の迂回は不要 diff --git a/builtins/ja/policies/review.md b/builtins/ja/policies/review.md index 1abdfdb..2921def 100644 --- a/builtins/ja/policies/review.md +++ b/builtins/ja/policies/review.md @@ -38,9 +38,11 @@ - オブジェクト/配列の直接変更 - エラーの握りつぶし（空の catch） - TODO コメント（Issue化されていないもの） -- 3箇所以上の重複コード（DRY違反） +- 本質的に同じロジックの重複（DRY違反） - 同じことをするメソッドの増殖（構成の違いで吸収すべき） - 特定実装の汎用層への漏洩（汎用層に特定実装のインポート・分岐がある） +- 内部実装のパブリック API エクスポート（インフラ層の関数・内部クラスが公開されている） +- リファクタリングで置き換えられた旧コード・旧エクスポートの残存 - 関連フィールドのクロスバリデーション欠如（意味的に結合した設定値の不変条件が未検証） ### Warning（警告）