coding-guardian

name	coding-guardian
description	Enforce this repository's real React, Hono, Drizzle, and TypeSpec rules while editing code, docs, or tooling.

Coding Guardian

この skill は、このリポジトリで実際に fail する規約と検証フローから外れないようにガードします。

• 返答言語: AGENTS.md に従う
• 重要: まず CODING_STANDARDS.md と enforcement entrypoint を読む
• 重要: API 契約の正は packages/typespec/main.tsp
• 重要: 生成物は手編集しない
• 重要: frontend は React + TSX + Vite + React Router であり、packages/frontend/web や SvelteKit 前提を持ち込まない
• 重要: backend は TypeScript + Hono + Cloudflare Workers + Drizzle であり、Go / Gin / GORM 前提を持ち込まない
• 重要: pnpm lint には OpenSpec validate と Scenario coverage check が含まれる

Workflow

1) Load the repository rules before editing

最初に次を読む。

• AGENTS.md
• CODING_STANDARDS.md
• CONTRIBUTING.md
• .opencode/skills/coding-guardian/references/repo-entrypoints.md

特に重要な enforcement entrypoint:

• root flow: package.json, .github/workflows/ci.yml, .husky/pre-commit, .husky/commit-msg, .lintstagedrc.json, commitlint.config.js, eslint.config.js
• TypeSpec / codegen: packages/typespec/package.json, packages/typespec/tspconfig.yaml, packages/typespec/README.md, packages/frontend/orval.config.ts
• frontend: packages/frontend/package.json, packages/frontend/tsconfig.*.json, packages/frontend/src/app/**, packages/frontend/src/domain/**, packages/frontend/src/api/**, packages/ui/**
• React Compiler: packages/build-config/react-compiler.js, packages/frontend/vite.config.ts, packages/frontend/vitest.app.config.ts, packages/ui/vitest.config.ts, scripts/eslint/**
• backend: packages/backend/package.json, packages/backend/tsconfig.*.json, packages/backend/src/entry/**, packages/backend/src/app/**, packages/backend/src/http/**, packages/backend/src/persistence/**, packages/backend/src/usecases/**, packages/backend/src/domain/**, packages/backend/src/types/**, packages/backend/src/drizzle/**, packages/backend/src/http/contracts/openapi-contract.test.ts
• OpenSpec: scripts/openspec/verify-change-intent.mjs, scripts/openspec/verify-scenario-coverage.mjs, scripts/openspec/verify-change-task-scope.mjs, scripts/openspec/verify-wireframe-previews.mjs

2) Classify the change before editing

• Contract / codegen: packages/typespec/**, packages/frontend/src/api/**, packages/frontend/orval.config.ts
• Frontend: packages/frontend/src/app/**, packages/frontend/src/domain/**, packages/ui/**
• Backend: packages/backend/**
• Tooling / workflow: root config, scripts, hooks, CI, .opencode/**

固定の依存方向:

• Client: packages/frontend/src/app -> packages/frontend/src/domain -> packages/frontend/src/api and packages/frontend/src/app -> packages/ui
• Server: packages/backend/src/entry -> packages/backend/src/app -> (packages/backend/src/http | packages/backend/src/persistence | packages/backend/src/usecases) -> packages/backend/src/domain -> packages/backend/src/types
• Persistence schema: packages/backend/src/persistence -> packages/backend/src/drizzle

3) Implement without breaking enforced rules

• Contract を変えるときは packages/typespec/main.tsp を直し、pnpm gen:api-sdk と pnpm check:codegen で整合を取る
• packages/typespec/openapi/openapi.json と packages/frontend/src/api/generated/client.ts は手で直さない
• Frontend app / domain で fetch, globalThis.fetch, axios, cross-fetch を直接使わない
• Frontend app の pages / components から @cfreact-template/frontend/api を直 import しない。domain hook を経由する
• React と TSX はこの repo の正規 frontend 実装であり、Svelte 用の制約へ読み替えない
• frontend/domain/UI の手書き React コードは @cfreact-template/build-config/react-compiler の共通設定でコンパイルし、runtime source から build tooling を import しない
• app components では React 組み込み Hook を使わず、domain と手書き UI の通常の useMemo / useCallback / memo は Compiler へ委譲する。上流由来の対象外は scripts/eslint/disable-policy.mjs へ集約する
• ESLint の単発例外は許可リストにある1ルールだけを構造化した eslint-disable-next-line で管理し、頻出する非互換 API は scripts/eslint/disable-policy.mjs の専用境界へ集約する
• packages/frontend/src/domain/hooks/** では use* export、{ data, actions } 戻り値、*Data / *Actions 型注釈を守る
• 再利用したい見た目は @cfreact-template/ui に寄せ、画面固有の構成だけを packages/frontend/src/app に置く
• Backend HTTP は packages/backend/src/http、配線は packages/backend/src/app、永続化は packages/backend/src/persistence / packages/backend/src/drizzle に置く
• packages/backend/src/http から packages/backend/src/persistence を直 import しない。c.env も HTTP 層で直接読まない
• packages/backend/src/domain と packages/backend/src/usecases では adapter import や framework 依存を持ち込まない
• packages/**/src/**/*.{ts,tsx} の export は、生成物とテストを除き TSDoc を付ける
• OpenSpec を触るときは openspec/specs/**/spec.md の Scenario ID とテストタイトルの参照を崩さない

4) Verify with the real repo flow

変更内容に応じて、少なくとも次を実行する。

• Contract / generated 変更: pnpm gen:api-sdk -> pnpm check:codegen
• TypeSpec 変更: pnpm format:check -> pnpm check
• JS / TS / TSX 変更: pnpm lint -> pnpm test:run
• Frontend-focused 変更: pnpm test:frontend
• Backend-focused 変更: pnpm test:backend
• Release-ready な変更や横断変更: pnpm build
• Skill 変更: python3 .opencode/skills/opencode-skills-devkit/scripts/validate_skills.py --root .

Changed-file 向けの軽量チェック:

• .opencode/skills/coding-guardian/scripts/check_changed.sh [base]

5) What to report back

• 触った領域
• どの enforced rule に合わせて設計したか
• 生成が必要だったか、実行したか
• 実行した command と結果
• まだ未実行の verify があれば、その理由

Common violations to prevent

• generated file の手編集
• packages/frontend/src/app から @cfreact-template/frontend/api の直 import
• frontend app / domain での fetch / axios / cross-fetch
• hooks が { data, actions } を返さない
• React Compiler 設定を frontend/UI ごとに複製する、または runtime source から build tooling を参照する
• 頻出する Compiler 非互換 API を専用境界外から直接 import する
• 理由・代替案・不採用理由・再評価条件のない eslint-disable-next-line
• export に必要な TSDoc がない
• packages/backend/src/http から packages/backend/src/persistence の直 import
• HTTP 層での c.env 直接参照
• OpenSpec の Scenario ID とテスト参照の不整合