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 |
| MongoDB | mongodb-silk |
| LLM, 埋め込み, ベクターストア, RAG | rag-spider |
フレームワークスキルがフレームワークのメカニズムを決定し、このスキルが原則を決定します。競合しているように見える場合は、構文についてはフレームワークスキルに従い、構造についてはこのスキルに従ってください。
コードを変更する前に
- まず実際のコードを読んでください。 フォルダ構造、モデル、設定、および変更しようとしているファイルを確認してください。フィールド名、関数シグネチャ、ファイル名、インポートパスを推測しないでください。実際のコードを読んでください。(推測した
dateが実際のexpense_dateの代わりになると、スキーマ、ヘルパー、レスポンスが一度に壊れたことがあります。)インストール済みのライブラリの動作がわからない場合は、仮定するのではなく実際のAPIを確認してください。 - 最初にルートを決定してください。 機能の場合、実装する前に各エンドポイント(メソッド、パス、リクエスト、レスポンス、ステータスコード、認証)をリストアップしてください。
- スコープは要件から生じます。 問題ステートメントが必要とするものだけを構築してください。誰も求めていない追加のエンドポイント、分析、キャッシュ、レート制限、再ランキング、コスト追跡、ダウンロード/検索エンドポイントは、「将来的に可能」と1行で言及するだけで、構築しないでください。
- 動作している振る舞いを保持してください。 関数を書き換えるときは、現在の動作(フィルター、ページネーション、バリデーション、ロギング、レスポンスフィールド)をリストアップし、新しいバージョンでもそれらすべてが実行されることを確認してください。
階層
ルート -> ヘルパー -> サービス -> データベース / 外部システム
| |
ユーティリティ ユーティリティ
| フォルダ | 所有するもの | 含んではならないもの |
|---|---|---|
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。
コードルール
- クラスベースのモジュール。 ヘルパー、サービス、ユーティリティはクラスです。ステートレスなコードには
@staticmethod/@classmethodを使用し、クラスが依存関係(注入されたセッションやクライアントなど)を保持する場合にのみインスタンスを使用します。ルートファイルとDjangourls.pyはモジュールレベルのままにします。2つの実際の実装なしに、継承、抽象基底クラス、インターフェースを強制しないでください。 - 関数は約40~50行に抑えてください。 長い関数は、同じクラス内の意味のあるメソッドに分割してください(例:
list_expenses→parse_filter_parameters+apply_expense_filters)。任意のチャンクに分割しないでください。 _で始まる関数名は禁止。関数内で定義された関数は禁止。 ネストされたデコレート関数の代わりに、app.add_exception_handler(...)などの明示的な呼び出しでハンドラーを登録してください。- すべてのインポートはファイルの先頭に、 stdlib → サードパーティ →
app.*の順にグループ化してください。循環インポートは、関数内でインポートするのではなく、コードを適切なモジュールに移動することで修正してください。唯一認められる例外は、create_app()内のFlaskブループリントのインポートです。 - 自作のロジックの代わりに確立されたライブラリを使用してください:
password-validator、email-validator/EmailStr、PyJWT、bcrypt、LangChainローダーとスプリッター、httpx。 - バリデーションは1回だけ。 Pydanticスキーマですでにルールが適用されている場合は、ヘルパーで再チェックしないでください。
- 1つのリクエストで同じことを2回計算せず、即座に失敗してください。 コストのかかるチェックの前に安価なチェックを行ってください(bcryptハッシュの前に重複メールチェック)。
- ハードコードされた設定は禁止: URL、モデル名、制限、top_k、温度、シークレットは
config.pyから取得してください。 - デッドコードは禁止: 未使用の関数、未使用のインポート、空のプレースホルダーファイル、
startappの残骸は削除してください。 - すべてのクラスとパブリックメソッドに型ヒントと1行のdocstring を付けてください。コメントは、理由が明らかでない場合にのみ記述してください。
- 例外を決して無視しないでください。 対処できる特定の例外はキャッチし、残りはグローバルハンドラーに到達させてください。
過剰エンジニアリングチェック
新しいファイル、クラス、層、依存関係、またはパターンを追加する前に、現在の要件にそれが必要かどうか、そして既存のもので対応できないかどうかを自問してください。これらはすべて構築された後に削除されました:
- アプリケーションが実行される前の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.md | 1つのサービスが別のリポジトリ、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.py | app/utils/log_utils.py |
assets/common_schema.py | app/schemas/common_schema.py |
assets/config.py | app/config.py |
assets/env.example | .env.example |
assets/gitignore | .gitignore(「常に」セクションと、該当するマークされたセクションのみ) |