Verdent Docs
エージェントとルール

ルールシステムと動作ガイダンス

ルールシステムによる Verdent の動作制御

ルールファイルは、コーディングセッション中に Verdent がどのように動作し応答するかを定義する Markdown ドキュメントです。AI エージェントの動作、出力の整形、意思決定、プロジェクト標準への準拠を導きます。

**目的:**ルールを使うと、コードや設定を変更せずに Verdent の動作をカスタマイズできます。コーディング規約、推奨パターン、コミュニケーションスタイル、タスク実行の好みを定め、それらをセッションをまたいで維持します。

**ルールの仕組み:**Verdent は会話中にルールファイルを継続的に参照し、コード生成、分析、ドキュメント作成、意思決定にガイドラインを適用します。ルールはすべてのエージェント応答に影響し、ユーザーの好みとの一貫性を保ちます。

3 つのカテゴリ:

  • グローバル設定 (VERDENT.md) - 個人のコーディングスタイル、言語設定
  • プロジェクト固有の標準 (AGENTS.md) - チームの規約、アーキテクチャパターン
  • プランのカスタマイズ (Plan.md) - Plan Mode の出力形式と内容

**ルールの優先順位:**ルールが競合した場合、Verdent は次の優先順位を適用します: AGENTS.md(最高)→ VERDENT.md(中)→ デフォルト(最低)


ユーザールール (VERDENT.md)

VERDENT.md は、すべてのプロジェクトとセッションに適用されるグローバル設定を定義します。個人のコーディングスタイル、好みのツール、コミュニケーションの好み、デフォルトの動作を定めます。

場所とスコープ

ファイルの場所: ~/.verdent/VERDENT.md

スコープ: すべてのプロジェクトに対してグローバル

アクセス方法:

  • Settings → Rules → User Rules
  • ~/.verdent/VERDENT.md でファイルを直接編集

**変更の反映タイミング:**ルールは新しい会話で即座に適用され、現在の会話の応答にも影響します。


ユースケース

コーディング設定

  • インデントスタイル(2 スペース、4 スペース、タブ)
  • 命名規則(camelCase、snake_case、PascalCase)
  • 好みの言語機能(ES6+、TypeScript strict モード、型ヒント)

すべてのプロジェクトに適用される個人のコーディングスタイルと規約を定義します。

出力言語

  • デフォルトの応答言語(例: 「常にスペイン語で応答する」)
  • 専門用語の扱い(「フランス語に該当する語がない場合は英語の用語を使う」)

Verdent が応答や説明で使う言語を制御します。

コードコメント

  • 好みの詳細度(「詳細なコメント」と「最小限のコメントのみ」)
  • コメントの言語(「コメントはフランス語で書く」)

コードにどの程度、どの言語でコメントを付けるかを指定します。

ドキュメントスタイル

  • コードのドキュメント化方法(JSDoc、TSDoc、docstring)
  • ドキュメントに使用例を含める

API のドキュメントとコードドキュメントの形式の標準を設定します。

コミュニケーション

  • 応答のトーンと冗長さ(「簡潔な説明」と「詳細な説明」)
  • 説明スタイル(「先にコードを示し、後で説明する」)

Verdent があなたにどのように情報を伝え提示するかをカスタマイズします。


形式と構文

VERDENT.md は、箇条書きや番号付きリストを用いたプレーンな Markdown 形式を使用します。

構造:

# User Rules

## Code Style Preferences
- Always use TypeScript strict mode
- Prefer functional components in React
- Include JSDoc comments for exported functions

## Documentation
- Add JSDoc comments for all exported functions
- Include usage examples in component documentation

## Communication
- Provide explanations before showing code
- Highlight breaking changes explicitly

書き方:

  • 明確で指示的な表現を使う(「常に〜する」「〜を優先する」「決して〜しない」)
  • 見出しを使って論理的なセクションに整理する
  • 個々のルールは箇条書きで書く
  • 望む動作を具体的に書く

開発者タイプ別の例

# User Rules

## TypeScript Preferences
- Use strict mode in tsconfig.json
- Prefer interfaces over type aliases for object shapes
- Include return types on all functions
- Use const assertions where appropriate

## Code Organization
- One component per file
- Named exports instead of default exports
- Organize imports: external, internal, types

## Documentation
- TSDoc comments for public APIs
- Include @param and @returns tags

**適用例:**Verdent に新しい React コンポーネントの作成を依頼すると、自動的に次を行います:

  • strict モードで TypeScript を使う
  • 名前付きエクスポート(デフォルトではなく)を作成する
  • @param/@returns タグ付きの TSDoc コメントを追加する
  • インポートをカテゴリ別に整理する
# User Rules

## Python Style
- Follow PEP 8 conventions
- Use type hints for function signatures
- Prefer list comprehensions over map/filter

## Data Analysis
- Use pandas for data manipulation
- Include DataFrame.head() after transformations
- Document assumptions about data

## Output Format
- Show shape and info() after operations
- Include visualization examples

**適用例:**Verdent にデータ分析コードの作成を依頼すると、次を行います:

  • データ操作に pandas を使う
  • すべての関数に型ヒントを付ける
  • 変換後に DataFrame.head() と shape を表示する
  • データの前提を記録するインラインコメントを追加する
# User Rules

## JavaScript Preferences
- Use ES6+ features (arrow functions, destructuring)
- Async/await over promises
- Template literals for string interpolation

## Testing
- Jest for unit tests
- Include test cases for edge conditions
- Aim for 80%+ code coverage

## Code Review
- Flag potential performance issues
- Suggest security improvements

**適用例:**Verdent は次を行います:

  • ES6+ 構文でモダンな JavaScript を書く
  • promise チェーンの代わりに async/await を使う
  • カバレッジ 80% を目標とした Jest テストを生成する
  • パフォーマンスとセキュリティの懸念を能動的に指摘する
# User Rules

## Communication
- Always respond in French
- Use technical English terms when no French equivalent exists
- Provide French variable/function names when appropriate

## Code Comments
- Write comments in French
- Documentation in both French and English

**適用例:**Verdent のすべての応答はフランス語になり、適切な場合は専門用語を英語にします。コードコメントとドキュメントもあなたの言語設定に従います。

# User Rules

## Code Style
- Minimal comments - code should be self-documenting
- Short, focused functions (< 20 lines)
- Avoid unnecessary abstractions

## Output Preferences
- Brief explanations
- Show code first, explain after
- No verbose documentation unless requested

**適用例:**Verdent は次を行います:

  • 簡潔で自己説明的なコードを生成する
  • 関数を 20 行未満に保つ
  • コードを示した後に簡潔な説明を添える
  • 明示的に要求しない限り冗長なコメントを避ける

作成と編集の方法

ほとんどのユーザーに推奨

  1. Verdent の上部バーで Settings ボタンを選択します
  2. ドロップダウンから Rules を選択します
  3. User Rules を選択します
  4. VS Code エディタでファイルが開きます
  5. Markdown 形式で編集します
  6. ファイルを保存します(Cmd+S / Ctrl+S

この方法では、ファイルが自動的に見つかり、デフォルトのエディタで開かれます。

上級ユーザーに推奨

  1. ~/.verdent/VERDENT.md に移動します
  2. 任意のテキストエディタで開きます
  3. Markdown の内容を編集します
  4. 変更を保存します

設定ファイルを直接扱うのが好みなら、この方法の方が速いです。


プロジェクトルール (AGENTS.md)

AGENTS.md は、現在のプロジェクトのエージェント動作を制御するプロジェクト固有のルールを定義します。チームのコーディング標準、アーキテクチャパターン、テスト要件、そのプロジェクト特有の開発ワークフローを定めます。

場所とスコープ

ファイルの場所: プロジェクトのルートディレクトリ

スコープ: 現在のプロジェクトのみ

バージョン管理: チーム全体での共有のために git にコミット可能

アクセス方法:

  • Settings → Rules → Project Rules
  • <project-root>/AGENTS.md で直接編集

ユースケース

チーム規約

すべてのチームメンバーが従う共通のコーディング標準:

  • チーム全体で一貫したインデント
  • コンポーネント/関数の命名規則
  • ファイル構成パターン

開発チーム全体で一貫したコーディングスタイルを強制します。

アーキテクチャパターン

プロジェクト固有の設計パターン:

  • MVC、マイクロサービス、モノレポ構造
  • 状態管理のアプローチ(Redux、Context、Zustand)
  • API 設計パターン(REST、GraphQL)

プロジェクトのアーキテクチャ上の決定とパターンを定義します。

テスト要件

期待されるテストカバレッジとフレームワーク:

  • 最小カバレッジのしきい値(80%、90%)
  • テストフレームワーク(Jest、pytest、Vitest)
  • テストファイルの命名規則

プロジェクトのテスト標準と品質ゲートを確立します。

開発ワークフロー

ビルドコマンド、デプロイ手順、PR ガイドライン:

  • テストの実行方法(pnpm testnpm run test
  • 特定パッケージのビルドコマンド
  • PR タイトルの形式要件

チームのワークフローと開発手順を文書化します。

テクノロジー制約

承認されたライブラリとフレームワークのバージョン:

  • 許可された依存関係
  • フレームワークのバージョン要件
  • プラットフォームサポート(iOS 14+、Android API 26+)

技術スタックの選択を制御し、一貫性を維持します。

**チームコラボレーション:**AGENTS.md はプロジェクトのルートに保存され、バージョン管理にコミットできるため、すべてのチームメンバーが一貫したエージェント動作で作業できます。

AGENTS.md をバージョン管理でチームと共有し、すべてのメンバー間で一貫した AI 動作を確保しましょう。


形式と構文

AGENTS.md は、構造化されたセクションと箇条書きを用いた Markdown 形式を使用します。VERDENT.md と似ていますが、プロジェクト固有の要件に焦点を当てます。

構造:

# AGENTS.md

## Dev environment tips
- Command for navigating workspace
- Installation commands
- Environment setup instructions

## Testing instructions
- Test execution commands
- Coverage requirements
- CI/CD integration details

## PR instructions
- Title format requirements
- Pre-commit checklist
- Review guidelines

書き方:

  • 命令的で指示的な表現
  • ワークフロー領域(開発、テスト、デプロイ)ごとに整理
  • 具体的なコマンドと手順
  • 個人の好みではなく、チーム全体の標準

プロジェクトタイプ別の例

# AGENTS.md

## Dev environment tips
- Use `pnpm dlx turbo run where <project_name>` to jump to a package
- Run `pnpm install --filter <project_name>` to add package to workspace
- Check the name field in package.json to confirm the right name

## Testing instructions
- Run `pnpm turbo run test --filter <project_name>` for all checks
- From package root: `pnpm test`
- Focus on one test: `pnpm vitest run -t "<test name>"`
- Fix all errors before merge

## PR instructions
- Title format: [<project_name>] <Title>
- Always run `pnpm lint` and `pnpm test` before committing

**適用例:**このモノレポで作業するとき、Verdent は次を行います:

  • ナビゲーションとテストに turbo コマンドを使う
  • PR タイトルにプロジェクト名のプレフィックスを付ける
  • コミットを提案する前に lint とテストのコマンドを実行する
# AGENTS.md

## Code Standards
- Use functional components with hooks
- TypeScript strict mode required
- Named exports only (no default exports)
- PropTypes or TypeScript interfaces for all components

## File Organization
- One component per file
- Components in `src/components/`
- Hooks in `src/hooks/`
- Utils in `src/utils/`

## Testing
- Jest + React Testing Library
- Test all user interactions
- 80%+ coverage required

**適用例:**Verdent が作成するすべての React コンポーネントは次のようになります:

  • フックを使う関数コンポーネント
  • TypeScript インターフェースを含む
  • 正しいディレクトリに配置される
  • カバレッジ 80% を目標とした Jest テストを含む
# AGENTS.md

## API Standards
- All endpoints include input validation
- Use async/await for asynchronous operations
- Consistent error format: { error: string, code: number }
- Rate limiting on public endpoints

## Security
- Never log sensitive data (passwords, tokens, PII)
- Parameterized queries only (prevent SQL injection)
- Validate and sanitize all inputs

## Testing
- Unit tests for all business logic
- Integration tests for API endpoints
- Test success and error cases

**適用例:**API エンドポイントを作成するとき、Verdent は次を行います:

  • 入力バリデーションを自動的に追加する
  • データベース操作にパラメータ化クエリを使う
  • 成功ケースとエラーケースの両方のテストを生成する
  • 機密データのログ出力を避ける
# AGENTS.md

## Platform Support
- iOS 14+ and Android API 26+
- React Native 0.72+
- Test on both platforms before PR

## State Management
- Use Redux Toolkit
- Async operations with Redux Thunk
- Normalize state shape

## Performance
- Images: WebP format, max 500KB
- Bundle size: monitor with bundle analyzer
- FlatList for long lists (>20 items)

**適用例:**モバイルアプリのコードは次のようになります:

  • 最小プラットフォームバージョンをサポートする
  • 状態管理に Redux Toolkit を使う
  • 画像を WebP 形式に最適化する
  • 長いリストのパフォーマンス向上のため FlatList を使う
# AGENTS.md

## Django Conventions
- Follow Django best practices and PEP 8
- Class-based views preferred
- Django ORM for database operations
- Migrations: never edit generated files

## Testing
- pytest-django for all tests
- Factory Boy for test fixtures
- Coverage must be 90%+

## Deployment
- Docker compose for local development
- Environment variables in .env (never committed)
- Run migrations before deployment

**適用例:**Django のコードは次のようになります:

  • クラスベースビューを使う
  • 生の SQL ではなく Django ORM を使う
  • Factory Boy フィクスチャ付きの pytest テストを生成する
  • テストカバレッジ 90% 以上を目標とする

VERDENT.md との違い

スコープ:

  • VERDENT.md: すべてのプロジェクトにまたがる個人の設定
  • AGENTS.md: 特定のプロジェクトのみのチーム標準

優先度:

  • AGENTS.md: 優先度が高い - プロジェクトの一貫性のために user_rules を上書きする
  • VERDENT.md: 優先度が低い - プロジェクトルールと競合しない場合に適用される

内容の焦点:

  • VERDENT.md: 個人のコーディングスタイル、コミュニケーションの好み、個人のツール
  • AGENTS.md: チーム規約、プロジェクトのアーキテクチャ、共有ワークフロー、技術スタック

バージョン管理:

  • VERDENT.md: 共有されない - 各自のマシンに留まる
  • AGENTS.md: git にコミットされる - チーム全体で共有される

保存場所:

  • VERDENT.md: ~/.verdent/VERDENT.md(グローバル)
  • AGENTS.md: プロジェクトのルートディレクトリ(プロジェクト固有)

競合解決の例:

VERDENT.md: "I prefer 2-space indentation"
AGENTS.md: "This project uses 4-space indentation"
→ Result: 4-space indentation (team standard wins)

どちらを使うべきか:

  • VERDENT.md: すべてのプロジェクトで適用したい個人の設定
  • AGENTS.md: このプロジェクトでチーム全体が従うべき標準

プランルール (Plan.md)

Plan.md は、Plan Mode で生成されるプランの内容と形式をカスタマイズします。プランの詳細度、含めるセクション、整形の好み、表示する情報を制御します。

場所とスコープ

ファイルの場所: ~/.verdent/plan_settings.json

スコープ: すべてのプロジェクトに対してグローバル

適用: プランを生成する Plan Mode のときのみ適用される

アクセス方法:

  • Settings → Rules → Plan Rules
  • ~/.verdent/plan_settings.json でファイルを直接編集

ユースケース

プラン構造

含めるセクションを定義します:

  • サマリー、前提条件、ステップ、検証
  • リスク評価、ロールバック手順
  • 所要時間の見積もり、クリティカルパス

すべてのプランに表示されるセクションと情報を制御します。

詳細度

粒度を制御します:

  • ハイレベルな概要(各 1〜2 時間のフェーズ)
  • 詳細な実装ステップ(15〜30 分のタスク)
  • 関数レベルの具体性(シグネチャ、ファイルパス)

実装プランの粒度と具体性を調整します。

形式の好み

提示スタイルを選択します:

  • 番号付きリストか箇条書きか
  • コードスニペットか説明か
  • 図(言葉で説明)

プラン情報の整形と表示方法をカスタマイズします。

情報の追加

追加要素を指定します:

  • 所要時間の見積もりをインラインで
  • リスクレベル(低/中/高)
  • チームコラボレーションのための役割割り当て
  • テスト要件の強調

コンテキストとメタデータを追加して、プランをより実行しやすくします。


形式と構文

Plan.md は、望むプラン構造と内容を記述するセクションを用いた Markdown 形式を使用します。

構造:


---
name: Plan Rules
version: 1.0.0
last_updated: 2025-11-26
---

## Plan Structure
- Start with brief summary (2-3 sentences)
- Include estimated time for each major step
- List prerequisites before implementation steps
- Identify potential risks

## Level of Detail
- Break tasks into subtasks of 15-30 minutes
- Include specific file paths for modifications
- List functions/components to create/modify

## Format
- Use numbered lists for sequential steps
- Use bullet points for options
- Include code snippets for complex changes

プランスタイル別の例

---
name: Detailed Technical
version: 1.0.0
last_updated: 2025-11-26
---

## Plan Structure
- Executive summary (2-3 sentences)
- Prerequisites and dependencies
- Numbered implementation steps
- Testing and verification strategy
- Rollback procedures

## Level of Detail
- Break into 20-30 minute tasks
- Specific file paths for all modifications
- Function signatures for new code
- Database schema changes with migration steps

## Format
- Numbered lists for sequence
- Code blocks for complex logic
- Diagrams for architecture changes (describe verbally)

**適用例:**プランには次が含まれます:

  • 先頭にエグゼクティブサマリー
  • 20〜30 分のタスク分解
  • src/components/Auth/Login.tsx のような具体的なファイルパス
  • async function authenticateUser(credentials: UserCredentials): Promise<AuthResult> のような関数シグネチャ
  • テストとロールバックの手順
---
name: High-Level Strategic
version: 1.0.0
last_updated: 2025-11-26
---

## Plan Structure
- Brief overview (1 paragraph)
- Major phases only (3-5 high-level steps)
- Key decisions and trade-offs
- Success criteria

## Level of Detail
- High-level phases (1-2 hours each)
- Avoid implementation specifics
- Focus on approach and strategy

## Format
- Bullet points for flexibility
- Minimal code examples
- Emphasize "why" over "how"

**適用例:**プランはハイレベルになり、次に焦点を当てます:

  • 3〜5 個の主要フェーズによる戦略的アプローチ
  • 実装の詳細より「なぜ」の説明
  • 決定ポイントとトレードオフ
  • 具体的な実装を伴わない成功基準
---
name: Time-Conscious
version: 1.0.0
last_updated: 2025-11-26
---

## Plan Structure
- Time estimates for each step
- Total project duration estimate
- Parallel tasks identified
- Critical path highlighted

## Level of Detail
- Tasks sized to 30-minute increments
- Dependencies clearly marked
- Blocking operations identified

## Format
- Include time estimates inline
- Mark parallel tasks
- Highlight critical path with bold

**適用例:**プランには次が含まれます:

  • 各ステップに所要時間の見積もり: 「認証ミドルウェアを作成(45 分)」
  • 合計所要時間: 「合計見積もり: 6 時間」
  • 並行可能なタスクの明示: 「ステップ 3 と並行して実行可能」
  • ブロッキング操作を示すためにクリティカルパスを太字に
---
name: Risk-Focused
version: 1.0.0
last_updated: 2025-11-26
---

## Plan Structure
- Risk assessment for each phase
- Mitigation strategies included
- Rollback procedures defined
- Testing requirements emphasized

## Level of Detail
- Identify potential failure points
- Document error handling approach
- Include recovery procedures

## Format
- Risk levels: low, medium, high
- Separate "Risks" section for each phase
- Mitigation steps in sub-bullets

**適用例:**各フェーズには次が含まれます:

  • リスク評価: 「リスク: 高(本番環境でのデータベースマイグレーション)」
  • 軽減策: 「まずステージングでマイグレーションを実行し、テストクエリで検証する」
  • ロールバック: 「問題が発生した場合は down スクリプトでマイグレーションを元に戻す」
---
name: Team Collaboration
version: 1.0.0
last_updated: 2025-11-26
---

## Plan Structure
- Role assignments for each task
- Coordination points identified
- Review checkpoints included
- Communication requirements

## Level of Detail
- Specify who handles each component
- List integration points between team members
- Include pair programming opportunities

## Format
- Use mentions for role assignments
- Mark collaboration points
- Include "Review required" markers

**適用例:**プランには次が指定されます:

  • 「バックエンド API(バックエンドチーム): 認証エンドポイントを作成」
  • 「連携ポイント: フロントエンドチームはバックエンドからの API 仕様を待つ」
  • 「レビュー必須: マージ前にセキュリティチームのレビュー」

プランルールはいつ適用されるか

プランルールの適用:

  • タイミング: プランを生成する Plan Mode のときのみ適用される
  • スコープ: プランの形式と内容を制御し、コード生成は制御しない
  • 独立性: VERDENT.md や AGENTS.md と競合しない

他のルールタイプの適用:

  • VERDENT.md: すべてのモード(Agent、Plan、Chat)で継続的に適用される
  • AGENTS.md: プロジェクト固有の動作のためにすべてのモードで継続的に適用される

相互作用の例:

Plan Mode activated:
1. VERDENT.md: "Use TypeScript" → Applied to code in plan
2. AGENTS.md: "Follow project conventions" → Applied to approach
3. plan_rules.md: "Include time estimates" → Applied to plan format
→ Result: Plan shows TypeScript code following project conventions with time estimates

モード固有の動作:

  • Agent Mode: VERDENT.md + AGENTS.md が適用される(plan_rules.md なし)
  • Plan Mode: VERDENT.md + AGENTS.md + Plan.md すべて適用される
  • Chat Mode: VERDENT.md + AGENTS.md が適用される(Plan.md なし)

ルールの優先順位と競合解決

ルールが競合した場合、Verdent は一貫した動作を保つために優先順位を適用します。

優先順位

1. プロジェクトルール (AGENTS.md) - 最高優先度プロジェクト固有のルールはグローバル設定を上書きします。一貫性のため、チーム標準が個人の設定より優先されます。

2. ユーザールール (VERDENT.md) - 中優先度プロジェクト固有のルールと競合しない場合にグローバル設定が適用されます。

3. デフォルト動作 - 最低優先度ルールが指定されていない場合に Verdent の組み込みデフォルトが適用されます。

競合解決の例:

VERDENT.md: "Use 2-space indentation"
AGENTS.md: "Use 4-space indentation for this project"
→ Result: Verdent uses 4-space indentation (project rules win)

プランルール: Plan.md は Plan Mode の間に独立して適用され、ユーザールール/プロジェクトルールと競合しません。プランの形式を制御し、VERDENT.md と AGENTS.md はプラン内のコードスタイルを制御します。

プランルールは Plan Mode の出力形式にのみ影響します。Verdent が解決策を分析・実装する方法は変わりません。

優先順位を覚えておきましょう: AGENTS.md(最高)→ VERDENT.md(中)→ デフォルト(最低)。競合では常にプロジェクトルールが優先されます。

詳細な競合解決アルゴリズム、競合時にどのルールが適用されているかを確認する仕組み、ルールを一時的に停止するための上書きの仕組みは、現在開発中です。


ルール競合のトラブルシューティング

ルールに反する予期しない動作が見られたら、次のデバッグ戦略に従ってください。

ステップ 1: 競合を特定する

  1. ルールに反する予期しない動作を観察する
  2. その状況にどのルールが適用されうるかを確認する
  3. ルールファイル間の矛盾を探す

ステップ 2: ルールの優先順位を確認する

AGENTS.md (highest) → VERDENT.md (medium) → defaults (lowest)

プロジェクトルールは個人の設定を上書きします。

ステップ 3: 単独でテストする

**VERDENT.md を無効にする:**一時的にファイルの名前を変更するか中身を消し、競合が解消されるかテストします

**AGENTS.md なしでテストする:**AGENTS.md のないプロジェクトで作業し、user_rules の動作を切り分けます

**新しい会話:**新しいセッションを開始し、会話のコンテキストによる影響を排除します


よくある競合シナリオ

シナリオ 1: 整形の競合

VERDENT.md: "Use 2-space indentation"
AGENTS.md: "Use 4-space indentation"
→ Resolution: AGENTS.md wins (project standard)
→ Fix: Accept project standard or discuss with team

シナリオ 2: 同一ファイル内の矛盾するルール

AGENTS.md:
- "Prefer functional components"
- "Use class components for complex state"
→ Resolution: Verdent interprets based on context
→ Fix: Clarify when each rule applies

修正例:

- Prefer functional components for simple UI
- Use functional components with hooks for complex state
- Only use class components for legacy code maintenance

シナリオ 3: ルールが曖昧すぎる

"Write good tests"
→ Problem: What is "good"?
→ Fix: "Generate unit tests with 80%+ coverage, include edge cases"

デバッグ戦略

**1. 明示的なテスト:**Verdent に「[特定の動作] についてどのルールに従っていますか?」と尋ねます

例:

You: "Which rule are you following for indentation?"
Verdent: "I'm using 4-space indentation from AGENTS.md (line 12),
which overrides your VERDENT.md preference for 2-space indentation."

**2. 段階的な改善:**曖昧なルールに具体性を加えます

ルール競合をデバッグするときは、ルールを 1 つずつ一時的に無効にし、どのルールが予期しない動作を引き起こしているかを切り分けます。

変更前:

- Use appropriate error handling

変更後:

- Wrap async operations in try/catch blocks
- Return error objects with message and code fields
- Log errors with context (function name, input parameters)

**3. 優先度マーカー:**譲れないルールには「CRITICAL:」や「REQUIRED:」を使います

## Security Rules
- **CRITICAL:** Never log passwords, API keys, or tokens
- **REQUIRED:** All user inputs must be validated and sanitized
- Preferred: Use parameterized queries for database operations

ルールを書くためのベストプラクティス

具体的で指示的に:

  • 明確で命令的な表現を使う(「常に〜する」「決して〜しない」「〜を優先する」)
  • 曖昧な表現を避ける(「〜しようとする」→「常に〜する」)
  • してほしくないことではなく、してほしいことを正確に述べる

良い例:

- Use async/await for asynchronous operations
- Include JSDoc comments for all exported functions

避けるべき例:

- Try to use modern JavaScript features
- Add comments when necessary

論理的に整理する:

  • 関連するルールをセクション見出しの下にまとめる
  • 関心事を分離する(スタイル、テスト、ドキュメント、セキュリティ)
  • ルールファイル全体で一貫した構造を使う

ルールを保守しやすく保つ:

  • 簡潔なルールを書く(箇条書き 1 つにつき 1 つの概念)
  • プロジェクトの進化に合わせてルールを見直し更新する
  • 不要になったルールは速やかに削除する

重要なルールを優先する:

  • 各セクションの先頭に重要なルールを配置する
  • 譲れない標準には強調を使う(「決して 認証情報をコミットしない」)
  • バグやセキュリティ問題を防ぐルールに焦点を当てる

ルールの効果をテストする:

  • 実際に Verdent がルールに従うか検証する
  • 新しい会話を開始してルールの適用をテストする
  • 実際のエージェント動作に基づいてルールを改善する

詳細さと柔軟性のバランスをとる:

  • 具体的すぎる → 適応しない硬直的な動作
  • 曖昧すぎる → 一貫しない動作
  • コンテキストに応じた判断の余地を残しつつ、明確なガイダンスを目指す

チームでの考慮事項 (AGENTS.md):

  • ルール作成にチームを関与させる
  • 自明でないルールには根拠を文書化する
  • チームルールは個人の好みではなく共有標準に集中させる

関連項目