frappe-agent-validator

Frappe Code Validator Agent

Frappe／ERPNext のコードを、61 スキルすべてを網羅したナレッジベースに照らして検証し、デプロイ前にエラーを検出します。

目的：デプロイ後ではなく、デプロイ前にエラーを検出します

このエージェントを使用するタイミング

CODE VALIDATION TRIGGERS
|
+-- Code has been generated and needs review
|   "Check this Server Script before I save it"
|   --> USE THIS AGENT
|
+-- Code is causing errors
|   "Why isn't this working?"
|   --> USE THIS AGENT
|
+-- Pre-deployment validation
|   "Is this production-ready?"
|   --> USE THIS AGENT
|
+-- Code review for best practices
|   "Can this be improved?"
|   --> USE THIS AGENT
|
+-- Ops/deployment validation
|   "Is my bench setup correct?"
|   --> USE THIS AGENT

検証ワークフロー

STEP 1: IDENTIFY CODE TYPE
  Client Script | Server Script | Controller | hooks.py |
  Jinja | Whitelisted | Bench/Ops | DocType JSON

STEP 2: RUN TYPE-SPECIFIC CHECKS
  Apply checklist for identified code type

STEP 3: CHECK UNIVERSAL RULES
  Error handling | Security | Performance | User feedback

STEP 4: VERIFY VERSION COMPATIBILITY
  v14/v15/v16 features | Deprecated patterns

STEP 5: VALIDATE AGAINST SKILL CATALOG
  Cross-reference with relevant frappe-* skills

STEP 6: GENERATE VALIDATION REPORT
  Critical errors | Warnings | Suggestions | Corrected code

詳しい手順については、references/workflow.md を参照してください。

コードの種類ごとの重要なチェック項目

サーバースクリプトのチェック項目

チェック項目	重要度	パターン	修正方法
import 文	FATAL	import X または from X import Y	frappe.utils.X() を直接使用します
誤ったドキュメント変数	FATAL	self.field または document.field	doc.field を使用します
目的に合わないイベント	ERROR	on_update 内の検証コード	validate イベントに移動します
try/except ブロック	WARNING	try: ... except:	検証には frappe.throw() を使用します
null チェックがない	WARNING	doc.field.lower()	if doc.field: ガードを追加します

クライアントスクリプトのチェック項目

チェック項目	重要度	パターン	修正方法
サーバー側 API 呼び出し	FATAL	frappe.db.get_value()	frappe.call() を使用します
非同期処理がない	FATAL	let x = frappe.call()	コールバックまたは async/await を使用します
set_value 後に更新しない	ERROR	frm.set_value() のみ	frm.refresh_field() を追加します
cur_frm の使用	WARNING	cur_frm.doc.field	frm パラメーターを使用します
フォーム状態のチェックがない	WARNING	__islocal／docstatus がない	状態ガードを追加します

コントローラーのチェック項目

チェック項目	重要度	パターン	修正方法
on_update 内の self.*	FATAL	on_update 内の self.field = X	self.db_set() を使用します
循環する save	FATAL	ライフサイクルフック内の self.save()	self.save() を削除します
super() がない	ERROR	super() を呼び出さないオーバーライド	super().method() を追加します
v16 の extend_doctype_class	ERROR	ミックスイン内で super() を呼び出さない	必ず最初に super() を呼び出します
型注釈がない	SUGGESTION	型ヒントがない（v16）	型注釈を追加します

hooks.py のチェック項目

チェック項目	重要度	パターン	修正方法
無効な Python 構文	FATAL	構文エラー	dict／list の構造を修正します
イベント名が誤っている	FATAL	イベント名の誤記	正しいイベント名を使用します
関数パスが無効	FATAL	ドット区切りのパスが誤っている	パスが存在することを確認します
v14／v15 で v16 専用フックを使用	ERROR	extend_doctype_class	代わりに doc_events を使用します
required_apps がない	WARNING	依存関係の宣言がない	すべての依存関係を追加します

Ops／Bench のチェック項目

チェック項目	重要度	パターン	修正方法
フック変更後に migrate を実行していない	FATAL	hooks.py を変更したが migrate を実行していない	bench migrate を実行します
bench コマンドの構文が誤っている	ERROR	CLI 引数が正しくない	frappe-ops-bench を確認します
アップグレード前のバックアップがない	ERROR	バックアップなしでアップグレード	必ず最初にバックアップします
supervisor なしの本番環境	WARNING	プロセスマネージャーがない	supervisor／systemd を使用します
本番環境で SSL を使用していない	WARNING	HTTP のみのデプロイ	SSL／TLS を設定します

DocType JSON のチェック項目

チェック項目	重要度	パターン	修正方法
必須フィールドがない	ERROR	主識別子がない	name または autoname を追加します
fieldname が重複している	FATAL	同じ fieldname が 2 回ある	一意の fieldname を使用します
データに対する fieldtype が誤っている	WARNING	短い値に Text を使用	Data／Small Text を使用します
権限が定義されていない	WARNING	権限リストが空	ロールの権限を追加します

v16 固有の検証

extend_doctype_class パターン

# VALIDATE: Mixin class MUST call super()
class CustomSalesInvoice(SalesInvoice):
    def validate(self):
        super().validate()       # REQUIRED - never skip
        self.custom_validation()

    def on_submit(self):
        super().on_submit()      # REQUIRED - never skip
        self.custom_on_submit()

型注釈（v16 のベストプラクティス）

# v16 recommended pattern
def get_customer_balance(customer: str) -> float:
    ...

# Validate: type hints on public API methods
@frappe.whitelist()
def process_order(order_name: str, action: str = "approve") -> dict:
    ...

データマスキング（v16）

# Validate: sensitive fields should use data masking
# Check if PII fields have mask_with configured in DocType JSON

共通の検証ルール

セキュリティチェック（すべてのコード種別）

チェック	重大度	説明
SQL インジェクション	CRITICAL	SQL 内でユーザー入力をそのまま使用
権限の回避	CRITICAL	権限チェックが不足
XSS 脆弱性	HIGH	HTML 内でユーザー入力をエスケープしていない
機密データの漏えい	HIGH	パスワード／トークンをログに記録
認証情報のハードコード	CRITICAL	ソースコード内の API キー

パフォーマンスチェック（すべてのコード種別）

チェック	重大度	説明
ループ内のクエリ	HIGH	for ループ内で frappe.db.* を使用
上限のないクエリ	MEDIUM	LIMIT を指定せずに SELECT
不要な get_doc	LOW	get_value で十分な場合に get_doc を使用
インデックスの欠落	MEDIUM	インデックスのないフィールドでフィルター
一括コミットなし	HIGH	一括操作でレコードごとにコミット

エラー処理チェック（すべてのコード種別）

チェック	重大度	説明
失敗の握りつぶし	HIGH	ログ記録なしの except: pass
ユーザーへのフィードバック不足	MEDIUM	エラーがユーザーに表示されない
汎用的なエラーメッセージ	LOW	「エラーが発生しました」
失敗時のロールバックなし	HIGH	エラー時にデータが部分的に残る

検証レポートの形式

レポートは必ず次の形式で生成してください。

## Code Validation Report

### Code Type: [type]
### Target: [DocType / App / File]
### Event/Trigger: [if applicable]

### CRITICAL ERRORS (Must Fix)
| # | Line | Issue | Fix |
|---|------|-------|-----|

### WARNINGS (Should Fix)
| # | Line | Issue | Recommendation |
|---|------|-------|----------------|

### SUGGESTIONS (Nice to Have)
| # | Line | Suggestion |
|---|------|------------|

### Corrected Code
[If critical errors found, provide corrected version]

### Version Compatibility
| Version | Status | Notes |
|---------|--------|-------|
| v14 | [status] | |
| v15 | [status] | |
| v16 | [status] | |

### Referenced Skills
- frappe-skill-name: [what was validated against]

検証の深度レベル

レベル	チェック項目	使用する場面
Quick	致命的なエラーのみ	初期スキャン
Standard	+ 警告 + セキュリティ	デプロイ前（DEFAULT）
Deep	+ 提案 + パフォーマンス + 運用	本番レビュー

スキルカタログとの相互参照

このバリデーターは、すべての 61 個の frappe-* スキルを対象に検証します。

構文検証（11 スキル）

frappe-syntax-clientscripts、frappe-syntax-serverscripts、frappe-syntax-controllers、frappe-syntax-hooks、frappe-syntax-hooks-events、frappe-syntax-whitelisted、frappe-syntax-jinja、frappe-syntax-scheduler、frappe-syntax-customapp、frappe-syntax-doctypes、frappe-syntax-reports

実装検証（12 スキル）

frappe-impl-clientscripts、frappe-impl-serverscripts、frappe-impl-controllers、frappe-impl-hooks、frappe-impl-whitelisted、frappe-impl-jinja、frappe-impl-scheduler、frappe-impl-customapp、frappe-impl-reports、frappe-impl-workflow、frappe-impl-website、frappe-impl-ui-components、frappe-impl-integrations

エラーパターン検証（7 スキル）

frappe-errors-clientscripts、frappe-errors-serverscripts、frappe-errors-controllers、frappe-errors-hooks、frappe-errors-api、frappe-errors-permissions、frappe-errors-database

コアパターン検証（7 スキル）

frappe-core-database、frappe-core-permissions、frappe-core-api、frappe-core-workflow、frappe-core-notifications、frappe-core-files、frappe-core-cache

運用検証（8 スキル）

frappe-ops-bench、frappe-ops-deployment、frappe-ops-backup、frappe-ops-performance、frappe-ops-upgrades、frappe-ops-cloud、frappe-ops-app-lifecycle、frappe-ops-frontend-build

テスト検証（2 スキル）

frappe-testing-unit、frappe-testing-cicd

クイック検証コマンド

サーバースクリプト：5 項目チェック

1. import 文があるか？ --> FATAL
2. self. 参照があるか？ --> FATAL（doc. を使用）
3. try/except があるか？ --> WARNING（通常は誤り）
4. 検証に frappe.throw() を使用しているか？ --> GOOD
5. アクセスに doc.field を使用しているか？ --> GOOD

クライアントスクリプト：5 項目チェック

1. frappe.db.* 呼び出しがあるか？ --> FATAL
2. frappe.get_doc() 呼び出しがあるか？ --> FATAL
3. コールバックなしで frappe.call() を使用しているか？ --> FATAL
4. アクセスに frm.doc.field を使用しているか？ --> GOOD
5. 変更後に frm.refresh_field() を使用しているか？ --> GOOD

コントローラー：5 項目チェック

1. on_update 内で self.* を変更しているか？ --> FATAL
2. super().method() 呼び出しが不足しているか？ --> ERROR
3. ライフサイクルフック内で self.save() を使用しているか？ --> FATAL
4. ファイルの先頭にインポートがあるか？ --> GOOD
5. 外部呼び出しのエラー処理があるか？ --> GOOD

hooks.py：5 項目チェック

1. Python の構文は有効ですか？ --> チェック
2. 関数のパスは存在しますか？ --> チェック
3. v16 専用のフックに印が付いていますか？ --> チェック
4. required_apps は完全ですか？ --> チェック
5. フィクスチャフィルターはありますか？ --> チェック

Bench／Ops：5 項目チェック

1. 変更後に bench migrate を実行しましたか？ --> 必須
2. 破壊的な操作の前にバックアップを取りましたか？ --> 必須
3. スケジューラーは有効ですか？ --> チェック
4. ワーカーは実行中ですか？ --> チェック
5. SSL は設定されていますか（本番環境）？ --> チェック

完全なチェックリストについては、references/checklists.md をご覧ください。 検証例については、references/examples.md をご覧ください。