エンジニアリングリファレンス · 33 件
AI コーディングガイドライン
AI エージェントとコードレビュアーのためのエンジニアリングガイドライン。ツールチェーン、日々の開発プラクティス、ライブラリ選定、プラットフォーム設計をタスク別に整理しています。
プロジェクトで使う
プロジェクトのディレクトリで実行し、現在のタスクにこのガイドラインを適用するようエージェントに指示してください。
pnpm dlx skills add fang2hou/ai-coding-guidelines@apply-guidelinesスキルをインストールせずに、次の指示を AI エージェントに送ることもできます。
https://github.com/fang2hou/ai-coding-guidelines のガイドラインを現在のタスクに適用してください。
PORTAL.md から始め、タスクに対応する文書を順番に読み、関連する規約に従ってください。まず読むべき基本文書
タスクに着手する前に、まずこの 2 本から読み始めてください。
タスク別の読み進め方
目的に合わせて、リンクされたガイドラインを順番に読み進めます。
TypeScript / フロントエンド開発
TypeScript バックエンド構築
Python API サービス開発
UI スタイリングと角丸設計
iOS 27 / macOS 27 Liquid Glass 対応
テスト・Git・CI/CD パイプライン
カテゴリ別に探す
すべてのガイドラインを領域ごとに整理しています。
原則
1 件判断の土台となる基本原則:速い検証、選択肢の絞り込み、根本原因の解決。
プラクティス
12 件日々の開発プラクティス:コーディング規約、テスト、ドキュメント、依存関係、セキュリティ。
- エージェント運用プロトコル自明でない変更を行う前に、AI エージェントは次の手順を踏むこと。
- AGENTS.md の執筆AGENTS.md はリポジトリにおける AI エージェントの入口であり、コードを書く前に読み込む作業コンテキストである。エージェントツールはセッション開始時にこれを読み込み、保持できるコンテキスト量にも上限があるため、各行には作業に必要…
- アーキテクチャガバナンスAI エージェントが誤って破ってはならないアーキテクチャの境界と不変条件を、ARCHITECTURE.md に明記する。
- 変更の規律自明でない変更をレビューに回す前に、運用プロトコルに従い、このチェックリストでも確認すること。
- コーディング規約選択した言語とフレームワークの確立された規約に従うこと。独自の流儀に置き換えないこと。
- 角丸角丸は要素ごとに決める値ではなく、プロジェクト全体で揃える体系である。少数のトークン段階を一度定義し、すべての角丸をそこから選ぶ。 2 つのルールですべての場面を網羅できる。単一のサーフェスには連続角丸、ネストしたサーフェスには同心の角丸…
- 依存関係の管理方針依存関係を追加する前に、次の 5 つの問いに順番に答えること。
- 言語ポリシー次の 3 つの言語はそれぞれ独立して決めること。ある言語の選択から、ほかの言語を推測してはならない。
- パイプラインこれらの規則は、GitHub Actions、GitLab CI、CircleCI、Jenkins など、あらゆるシステムの CI/CD パイプラインに適用する。選択したシステム固有の規則は、対応するツールチェーン文書に記載されている。
- 必須のプロジェクトドキュメントすべてのプロジェクトは、AGENTS.md、README.md、DEVELOPMENT.md、CONTRIBUTING.md を維持しなければならない。重要なアーキテクチャ上の境界を持つプロジェクトでは、ARCHITECTURE.md も…
- セキュリティ次のようなシークレットや機密情報をリポジトリにコミットしてはならない。
- テスト戦略テストはカバレッジの数字を稼ぐためではなく、実際の振る舞いを検証するために書く。
ツールチェーン
9 件言語ごとの標準ツールチェーン。ローカルと CI で同じツールを動かす。
- Databricksデータおよび AI ワークロードでは Databricks を優先する。アプリケーションのホスティングと管理には Databricks Apps、スケジュール実行や自動実行には Databricks Jobs を使う。
- Git ワークフロープロジェクトのすべてのコミットは、Conventional Commits 仕様に従わなければならない。
- GitHub ActionsGitHub Actions は標準の CI/CD プラットフォームであり、ユーザーがパイプラインシステムを指定していない場合のデフォルトである。ツールに依存しないパイプラインの規則は パイプライン に記載されている。
- Go ツールチェーンAI 支援開発のデフォルト言語は TypeScript と Python である。Go はデフォルトではなく、次の要件が実際に必要な場合に限って選ぶ。
- misemise をすべてのプロジェクトで必須とする。
- Python ツールチェーンPython と TypeScript は、ライブラリと AI エージェントのエコシステムが最も充実しているため、AI 支援開発のデフォルト言語とする。
- 品質ゲートprek を標準のプリコミットフレームワークとして使う。
- Rust ツールチェーンAI 支援開発のデフォルト言語は TypeScript と Python である。Rust はデフォルトではなく、次の要件が実際に必要な場合に限って選ぶ。
- TypeScript ツールチェーンTypeScript と Python は、ライブラリと AI エージェントのエコシステムが最も充実しているため、AI 支援開発のデフォルト言語とする。
ライブラリ
8 件フロントエンド・バックエンド・AI 機能で標準採用するライブラリとフレームワーク。
- Agentation条件付き — フロントエンドの反復開発とテスト中に Agentation を有効にし、視覚的なフィードバックを AI コーディングエージェント向けの構造化コンテキストに変換する。
- フロントエンドフレームワーク:Vite vs Next.js推奨 — フロントエンドフレームワークは Vite をデフォルトとし、Next.js はフルスタックの React 機能が本当に必要な場合に限り選択する。
- Go API スタック推奨 — Go の Web フレームワークには Echo を使い、リクエスト検証には github.com/go-playground/validator/v10 を使う。Go 自体の採用が Go ツールチェーンの基準に基づいて正当化され…
- Python API スタック推奨 — FastAPI + Pydantic + Uvicorn を標準の Python API スタックとする。3 つを別々に選ぶのではなく、1 つのスタックとして採用する。
- Svelte(Svelte 5 + SvelteKit)条件付き — Svelte 5 + SvelteKit は、開発の楽しさも目標のひとつである小規模な個人プロジェクトと実験プロジェクトでの採用を認める。デフォルトではない。本番のフロントエンドはフロントエンドフレームワークで選定した Re…
- Tailwind CSS条件付き — プロジェクトがすでに Tailwind を使っている、またはコンポーネントキットが Tailwind を必要とする場合に使う。新しいスタイリングのデフォルトはネイティブ CSS である。
- TypeScript バックエンド推奨 — TypeScript のバックエンドサービスには Hono を使う。既定のランタイムは Active LTS ラインの Node.js である。Web 標準 API によって、サービスを Cloudflare Workers な…
- Vercel AI SDK条件付き — Vercel AI SDK は、Next.js プロジェクトでストリーミングや UI 統合などの機能を実際に使う場合に限って採用する。
プラットフォーム
3 件Apple プラットフォーム(iOS / macOS 27 Liquid Glass)のデザインと実装パターン。
- Liquid Glass API リファレンスXcode 27 でビルドし、最低対応 OS をそれぞれ 27.0 に設定した iOS 27 とネイティブ macOS 27 のアプリを対象とする。2026-09-06 に Apple の文書と Xcode 27 ベータ版のビルド 27A…
- Liquid Glass の設計(Apple プラットフォーム)iOS 27 とネイティブの macOS 27 向けの新規アプリでは、システムのナビゲーションとコントロールを優先して Liquid Glass を採用する。標準コンポーネントで必要な操作を実現できない場合に限り、カスタムのガラス効果を追…
- Liquid Glass 実装パターンXcode 27 でビルドする iOS 27 とネイティブの macOS 27 アプリを対象とし、各プラットフォームの最低対応 OS を 27.0 に設定する。SwiftUI を基本とし、独自の組み込みには iOS で UIKit、mac…