Communityコーディング&開発github.com

バックエンドシルク: 共有バックエンド標準

Python(Flask、FastAPI、Django、FastMCP)およびNode.js(Express)を使用したバックエンドおよびAPIプロジェクト向けのコーディングスキルです。プロジェクト構造、ルーター、ヘルパー、サービスの階層化、クラスベースのコードルール、エラーハンドリングとステータスコード、エッジケース、ロギング、.env設定、認証とデータ所有権、リポジトリ間の通信、Gitルール、テストをカバーします。Pythonバックエンド、REST API、MCPサーバー、RAGバックエンドの作成、拡張、デバッグ、リファクタリング、レビューの際に使用してください。

バックエンドシルク: 共有バックエンド標準 とは?

Backend Silkは、Python(Flask、FastAPI、Django、FastMCP)およびNode.js(Express)を使用したバックエンドおよびAPIプロジェクト向けの共有エンジニアリング標準を定義するスキルです。このスキルの主な目的は、「間違った構造」(ロジックが間違った層にある、誰も必要としないファイル)と「過剰エンジニアリング」(動作するアプリケーションができる前の抽象化)という2つの失敗を防ぐことです。さらに、変更やリファクタリングによって以前動作していた動作が静かに失われるという、3つ目の見落とされがちな失敗も防ぎます。 このスキルは、ルーター、ヘルパー、サービス、ユーティリティ、スキーマ、モデル、プロンプト、設定からなる明確な階層構造を定義します。ルーターはビジネスロジックを含まず、URL、メソッド、認証、ステータスコード、レスポンスモデルのみを担当します。ヘルパーはビジネスロジック、検証、所有権チェック、オーケストレーションを処理します。サービスは外部システム(データベース、LLM、ベクターストアなど)とのインターフェースを提供します。ユーティリティは複数のモジュールで再利用されるクラスベースのコードを保持します。これらの層間の通信は一方向で、ルーターはヘルパーを呼び出し、ヘルパーはサービスを呼び出します。サービスがヘルパーを呼び出したり、ユーティリティがヘルパーを呼び出したりすることはありません。 コード作成ルールとして、クラスベースのモジュール、関数は40~50行程度、アンダースコアで始まる関数名や関数内関数の禁止、インポートはファイルの先頭にまとめる、確立されたライブラリの使用、Pydanticスキーマによる重複検証の防止、ハードコードされた設定の禁止、デッドコードの削除、型ヒントと1行のdocstring、例外の無視禁止などが定められています。また、過剰エンジニアリングを防ぐためのチェックリストも提供されており、新しいファイル、クラス、層、依存関係、パターンを追加する前に、現在の要件に本当に必要か、既存のもので対応できないかを問いかけることが推奨されています。 このスキルは、Claude Code、Cursor、Codex、Windsurf、Copilot、AiderなどのAIエージェントツールと連携して使用することを前提に設計されており、フレームワーク固有のスキル(flask-spider、fastapi-spider、django-spiderなど)のコンパニオンとして機能します。フレームワークスキルが構文を決定し、このスキルが構造の原則を決定します。競合が発生した場合は、構文についてはフレームワークスキルに従い、構造についてはこのスキルに従います。

対応~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/VivekShevale/eight-eye/tree/HEAD/skills/backend/backend-silk

Installed? Explore more コーディング&開発 skills: steipete/bluebubbles, steipete/eightctl, steipete/blucli · View all 6 →

お気に入りのAIに質問する

このエージェントスキルを事前に読み込んだ状態で新しいチャットを開きます。

ドキュメント

Backend Silk: 共有バックエンド標準

シニアPythonバックエンドエンジニアとして、シンプルでプロダクション品質のコードを書いてください。このスキルが存在する目的は、間違った構造(間違った層にあるロジック、誰も必要としないファイル)と過剰エンジニアリング(動作するアプリケーションができる前の抽象化)という2つの失敗を防ぐことです。3つ目の、より静かですが同様にコストがかかる失敗は、変更やリファクタリングによって以前動作していた動作が静かに失われることです。

コンパニオンスキル

命名規則: *-spider スキルは特定の種類のプロジェクトを構築し、*-silk スキルはすべてのスパイダーが紡ぐ共有標準です。このスキルはすべてのバックエンドで共有される原則を保持します。対応するコンパニオンもロードしてください:

状況併用するスキル
Flask / FastAPI / Django プロジェクトflask-spider / fastapi-spider / django-spider
Node.js / Express プロジェクトnode-spider (ここでのルールが適用され、PythonのコードサンプルはPythonです)
MCPサーバーまたはMCPクライアントmcp-spider
PostgreSQL, MySQL, SQLite (SQLAlchemy, Django ORM)sql-silk
MongoDBmongodb-silk
LLM, 埋め込み, ベクターストア, RAGrag-spider

フレームワークスキルがフレームワークのメカニズムを決定し、このスキルが原則を決定します。競合しているように見える場合は、構文についてはフレームワークスキルに従い、構造についてはこのスキルに従ってください。

コードを変更する前に

  1. まず実際のコードを読んでください。 フォルダ構造、モデル、設定、および変更しようとしているファイルを確認してください。フィールド名、関数シグネチャ、ファイル名、インポートパスを推測しないでください。実際のコードを読んでください。(推測した date が実際の expense_date の代わりになると、スキーマ、ヘルパー、レスポンスが一度に壊れたことがあります。)インストール済みのライブラリの動作がわからない場合は、仮定するのではなく実際のAPIを確認してください。
  2. 最初にルートを決定してください。 機能の場合、実装する前に各エンドポイント(メソッド、パス、リクエスト、レスポンス、ステータスコード、認証)をリストアップしてください。
  3. スコープは要件から生じます。 問題ステートメントが必要とするものだけを構築してください。誰も求めていない追加のエンドポイント、分析、キャッシュ、レート制限、再ランキング、コスト追跡、ダウンロード/検索エンドポイントは、「将来的に可能」と1行で言及するだけで、構築しないでください。
  4. 動作している振る舞いを保持してください。 関数を書き換えるときは、現在の動作(フィルター、ページネーション、バリデーション、ロギング、レスポンスフィールド)をリストアップし、新しいバージョンでもそれらすべてが実行されることを確認してください。

階層

ルート -> ヘルパー -> サービス -> データベース / 外部システム
            |            |
          ユーティリティ ユーティリティ
フォルダ所有するもの含んではならないもの
routes/ (Flaskブループリント、FastAPIルーター、Django views.py + urls.py、MCP tools/)URL、メソッド、認証依存関係/デコレータ、ステータスコード、レスポンスモデル、ヘルパーへの1回の呼び出しビジネスロジック、クエリ、バリデーションコード、try/except、ロギング
helpers/1つの機能のビジネスロジック。コントローラのように: スキーマを超えたバリデーション、所有権チェック、機能固有のクエリとフィルター、サービスのオーケストレーション、期待される失敗のHTTPエラーへのマッピング、レスポンスの構築DBセッションのオープン/クローズ、コミット/ロールバック、LLMまたはSDKクライアントの作成
services/それぞれ1つの外部システムまたはインフラストラクチャ部品: DB接続と汎用CRUD(db_service.py)、LLM、埋め込み、ベクターストア、PDF、メール、別のリポジトリのAPI機能固有のビジネスルール、HTTP知識(HTTPException、ステータスコード)、ヘルパーの呼び出し
utils/複数のモジュールで再利用されるクラスベースのコード: LogUtils、ErrorHandlers、AuthUtils、純粋なコンバーター1つの機能でのみ使用されるコード、外部API呼び出し
schemas/Pydanticリクエスト/レスポンスモデル(Django: serializers.py)DBモデル
models/永続化モデルビジネスロジック
prompts/コードとしてのプロンプトテンプレート(LLMを使用する場合のみ).env 内のプロンプト
config.py.env からロードされた1つの設定オブジェクトロジック

表から導き出されるルール:

  • 方向は一方通行です。 ルートはヘルパーを呼び出し、ヘルパーはサービスを呼び出します。サービスがヘルパーを呼び出すことはなく、ユーティリティがヘルパーを呼び出すこともありません。
  • データベースの分割。 ヘルパーは機能クエリ(フィルター、検索、所有権)を構築します。DBサービスはそれらを実行し、接続、セッション、コミット、ロールバックを所有します。詳細は sql-silk / mongodb-silk を参照してください。DjangoではORMがDB層となるため、db_service はありません。
  • パススルー層は禁止。 ヘルパーがサービスに転送するだけの場合は、ヘルパーを削除してサービスを直接呼び出してください。すべてのファイルはその存在価値を証明しなければなりません。
  • ユーティリティとヘルパー。 多くの場所で使用される → utils/。1つの機能で使用される → その機能のヘルパー。
  • 実際のニーズが生じたときにフォルダとファイルを作成し、事前に作成しないでください。1つの関数が新しいフォルダ(errors/、exceptions.py、core/)を正当化することは決してありません。既存の適切なクラスに追加してください。
  • 命名: <domain>_routes.py(<domain>_router、またはFlaskでは <domain>_bp を保持)、<domain>_helper.py → XHelper、<domain>_service.py → XService、<domain>_schema.py、<domain>_utils.py → XUtils、<name>_prompt.py → NAME_PROMPT。クラス名は常にそのフォルダと一致する必要があります(helpers/ 内の class ExpenseService は間違いです)。

完全なフォルダの役割と開始ツリー: references/architecture.md。

コードルール

  1. クラスベースのモジュール。 ヘルパー、サービス、ユーティリティはクラスです。ステートレスなコードには @staticmethod / @classmethod を使用し、クラスが依存関係(注入されたセッションやクライアントなど)を保持する場合にのみインスタンスを使用します。ルートファイルとDjango urls.py はモジュールレベルのままにします。2つの実際の実装なしに、継承、抽象基底クラス、インターフェースを強制しないでください。
  2. 関数は約40~50行に抑えてください。 長い関数は、同じクラス内の意味のあるメソッドに分割してください(例: list_expenses → parse_filter_parameters + apply_expense_filters)。任意のチャンクに分割しないでください。
  3. _ で始まる関数名は禁止。関数内で定義された関数は禁止。 ネストされたデコレート関数の代わりに、app.add_exception_handler(...) などの明示的な呼び出しでハンドラーを登録してください。
  4. すべてのインポートはファイルの先頭に、 stdlib → サードパーティ → app.* の順にグループ化してください。循環インポートは、関数内でインポートするのではなく、コードを適切なモジュールに移動することで修正してください。唯一認められる例外は、create_app() 内のFlaskブループリントのインポートです。
  5. 自作のロジックの代わりに確立されたライブラリを使用してください: password-validator、email-validator / EmailStr、PyJWT、bcrypt、LangChainローダーとスプリッター、httpx。
  6. バリデーションは1回だけ。 Pydanticスキーマですでにルールが適用されている場合は、ヘルパーで再チェックしないでください。
  7. 1つのリクエストで同じことを2回計算せず、即座に失敗してください。 コストのかかるチェックの前に安価なチェックを行ってください(bcryptハッシュの前に重複メールチェック)。
  8. ハードコードされた設定は禁止: URL、モデル名、制限、top_k、温度、シークレットは config.py から取得してください。
  9. デッドコードは禁止: 未使用の関数、未使用のインポート、空のプレースホルダーファイル、startapp の残骸は削除してください。
  10. すべてのクラスとパブリックメソッドに型ヒントと1行のdocstring を付けてください。コメントは、理由が明らかでない場合にのみ記述してください。
  11. 例外を決して無視しないでください。 対処できる特定の例外はキャッチし、残りはグローバルハンドラーに到達させてください。

過剰エンジニアリングチェック

新しいファイル、クラス、層、依存関係、またはパターンを追加する前に、現在の要件にそれが必要かどうか、そして既存のもので対応できないかどうかを自問してください。これらはすべて構築された後に削除されました:

  • アプリケーションが実行される前のpydantic-settingsまたはバリデーションフレームワーク(凍結されたdataclass設定で十分)
  • 1つのエラーのための新しい例外モジュールまたはクラス
  • サービスを呼び出すだけのヘルパー
  • あなたが所有する2つのサービス間のRS256キーペア(HS256共有シークレットで十分)
  • 格納された派生値(入力+出力が存在する場合の total_tokens)
  • 埋め込みリストで機能する場合の2つのコレクションまたはテーブル
  • 長いプロンプトと長いツールの説明

複数の設計が機能する場合は、プロダクションセーフである最もシンプルなものを選択してください。

リクエストとレスポンスのスキーマ(概要)

  • すべてのエンドポイントは、未知のフィールドとサーバー所有のフィールドを拒否するリクエストスキーマでボディとクエリパラメータをバリデーションします。バリデーション後のコードは、バリデーション済みオブジェクトのみを使用します。
  • すべての成功レスポンスはレスポンススキーマから構築されます: リソース自体(XResponse)、リスト {"items", "page", "page_size", "total", "total_pages"}、またはアクション結果スキーマ(TokenResponse)。エンベロープやハンドラー内で組み立てられたオブジェクトリテラルはありません。
  • ステータスコードは成功と失敗を伝えます: 200 読み取り/更新、201 作成、204 ボディなしの削除、エラーは ErrorResponse。失敗時に200を使用しないでください。

完全な契約と、フレームワークごとのスキーマの場所: references/api-design.md。

エラー(概要)

  • すべてのエラーレスポンスは、assets/common_schema.py からの1つの形状を持ちます: {"status": "error", "message": "...", "details": [{"field": "...", "message": "..."}]}(details はフィールドエラーがある場合のみ)
  • サービスはプレーンまたはライブラリの例外を発生させます。ヘルパーは予想されるケースに対してHTTPエラーを発生させます。utils/error_handlers.py の1つの ErrorHandlers クラスが依存関係エラーをマップし、その他すべてを500としてキャッチします。
  • ステータスコード: 400 不正な入力、401 認証されていない、404 欠落 または別のユーザーのレコード、409 重複、413 大きすぎる、422 スキーマバリデーション、424 自身の依存関係ダウン(データベース、ベクターストア)、429 アップストリームレート制限、502 アップストリームがエラーを返した、503 別のサービスに到達できない、504 アップストリームタイムアウト、500 予期しないエラー。失敗時に200を決して使用しないでください。
  • ユーザーには、トレースバック、ホスト、接続文字列、キーではなく、短い安全なメッセージが表示されます。

エッジケースのチェックリストとハンドラーパターン: references/errors-and-edge-cases.md。リポジトリ間の呼び出し: references/cross-repo-communication.md。

ロギング(概要)

1つの LogUtils クラス(assets/log_utils.py)が、起動時に .env の LOG_LEVEL と LOG_TO_FILE から1回設定されます。他のすべてのモジュールは logger = LogUtils.get_logger(__name__) のみを行います。フォーマットは %(asctime)s | %(levelname)s | %(name)s | %(message)s、メッセージは Event | key=value、シークレットや個人データは含めず、各障害は1回だけログに記録されます。詳細: references/logging.md。

設定とセキュリティ(概要)

  • config.py には、assets/config.py から .env からロードされた凍結されたdataclassがあります。.env.example はプレースホルダーとコメント付きでコミットされます(assets/env.example)。.env は決してコミットされません(assets/gitignore)。
  • パスワード: 登録時のみ password-validator ポリシー、bcrypt/werkzeugハッシュ、ログイン時は一般的な「Invalid email or password.」。
  • JWT: .env からのシークレット、ユーザーIDは検証済みトークンからのみ取得され、リクエストボディからは決して取得されません。
  • すべてのクエリは現在のユーザーにスコープされます。他のユーザーのレコードは404を返します。

詳細: references/security.md。API規則(メソッド、ページネーション、フィルタリング、検索パラメータ): references/api-design.md。

Gitとテスト(概要)

  • 決してコミットしないもの: .env、キー、認証情報、アップロード、ベクターデータ、ローカルデータベース、ログ、仮想環境、生成されたレポート。マイグレーションは、それらを生成したモデル変更とともにコミットされます。
  • コミットメッセージは Conventional Commits に従います(feat:、fix:、refactor:、chore:、test:、docs:、perf:)。1コミットに1つの関心事、1リポジトリに1コミットです。
  • テストは重要なパスをカバーします: 認証、ユーザー間の所有権、バリデーション、エラーレスポンス、依存関係の障害(モック化)。外部サービス(LLM、他のリポジトリ)はモック化されます。
  • 評価(ゴールデンデータセット、評価スクリプト、レポート)は、明示的に要求された場合にのみ存在します。rag-spider / mcp-spider を参照してください。

詳細: references/git-and-testing.md。

コードチェックリスト

  • 階層が尊重されている。パススルーファイルがない。クラス名がフォルダと一致している。
  • アンダースコアで始まる関数やネストされた関数がない。インポートは先頭。関数は約50行以下。
  • 既存の動作が保持されている(フィルター、ページネーション、バリデーション、レスポンスフィールド)。
  • すべてのエンドポイントにリクエストスキーマとレスポンススキーマがある。アドホックなレスポンスオブジェクトがない。
  • references/errors-and-edge-cases.md のエッジケースが正しいステータスコードで処理されている。
  • 新しい設定が config.py と .env.example にある。ハードコードされたものがない。コードやログにシークレットがない。
  • 適切な場所に、適切なレベルでロギングが追加されている。
  • 未使用のインポートやデッドコードが残っていない。

リファレンスファイル(必要な場合のみ読む)

ファイル読むタイミング
references/architecture.mdプロジェクトの作成、機能フォルダの追加、コードの属する場所がわからない場合
references/errors-and-edge-cases.mdエンドポイント、エラーハンドラーを作成する場合、または障害パスをレビューする場合
references/cross-repo-communication.md1つのサービスが別のリポジトリ、MCPサーバー、または外部APIを呼び出す場合
references/logging.mdロギングの設定またはレビュー時
references/security.md認証、パスワード、JWT、アップロード、シークレット、CORS
references/api-design.mdエンドポイント、リクエスト/レスポンススキーマ、ページネーション、フィルター、検索の設計時
references/git-and-testing.mdコミット、PRの説明、決してコミットしてはいけないもの、テスト、デバッグアプローチ

アセットファイル(プロジェクトにコピーして適応)

テンプレートは選択的にコピーしてください: このプロジェクトが現在使用する部分のみを保持してください(.gitignore のセクション、.env.example のキー、設定フィールド)。プロジェクトにない機能の残りの行はノイズとなり、次の読者を誤解させます。

ファイル変換先
assets/log_utils.pyapp/utils/log_utils.py
assets/common_schema.pyapp/schemas/common_schema.py
assets/config.pyapp/config.py
assets/env.example.env.example
assets/gitignore.gitignore(「常に」セクションと、該当するマークされたセクションのみ)

関連スキル