developers-amsterdam

アムステルダム市エンジニアリング標準

必須: すべてのアーキテクチャ、技術スタック、エンジニアリング上の決定は、これらの標準に従わなければなりません。ユーザーの明示的な承認なしに、承認済みリスト以外のフレームワーク、データベース、パターンを推奨しないでください。新しいプロジェクトをセットアップする際は、常に初日からこれらの標準を適用してください。

Gemeente Amsterdam のすべてのプロジェクト向けの開発標準であり、Engineering Enablement が保守しています。

ポータル: https://developers.amsterdam/ ソース: https://github.com/Amsterdam/development-standards ライセンス: CC0 1.0 Universal

構築前に明確化する

ユーザーのリクエストが曖昧な場合（例:「API を作って」「新しいプロジェクトをセットアップして」「サービスを作成して」）、仮定する前に質問してください。以下の決定ゲートを提示してください — これらは下記の選択表に対応しています:

決定事項	選択肢	重要な理由
バックエンド言語	Python（Django または FastAPI）または Node.js（TypeScript + NestJS）	スタック全体、テストフレームワーク、プロジェクト構造を決定します
Python フレームワーク	Django（標準）または FastAPI（非同期/高性能）	プロジェクトレイアウト、ORM、テストパターンが異なります
プロジェクト構造	単一パッケージまたは pnpm モノレポ	アプリ間でコードを共有する場合はモノレポ、単一のデプロイ単位なら単一パッケージ
データベース	PostgreSQL（デフォルト）、PostGIS（地理空間）、Cosmos DB（ドキュメント）	Docker セットアップ、マイグレーション、接続パターンに影響します
フルスタックまたは API のみ	Next.js/React Router（フルスタック）または API のみのバックエンド	フロントエンドのスキャフォールディングが必要かどうかを決定します
Git ワークフロー	GitLab Flow、Git Flow、またはトランクベース	トランクベースには成熟した CI/CD が必要です。Git Flow はリリーストレイン向けです

一度にすべてを尋ねないでください。 プロンプトが真に曖昧なままにしている 1～2 個の質問を選んでください。ユーザーが「FastAPI サービス」と言った場合 → Python + FastAPI + API のみがすべて暗黙に示されているので、必要に応じて構造とデータベースだけを明確にしてください。

クイック決定表

言語 & フレームワーク選択

ニーズ	選択	備考
バックエンド API（標準）	Python + Django	ほとんどのプロジェクトのデフォルトの選択
バックエンド API（高性能 / 非同期）	Python + FastAPI	非同期またはパフォーマンスが重要な場合
バックエンド API（JS エコシステム）	Node.js + TypeScript + NestJS	チームの専門知識が JS 中心の場合
フロントエンドアプリ	TypeScript + React	新規プロジェクトでは常に TypeScript
フルスタックアプリ	Next.js または React Router	Amsterdam Design System を使用
モバイル	React Native	Amsterdam App プラットフォームに統合
ローコード	Mendix	市民向けのシンプルなアプリ向け
地図	Leaflet	maps.developers.amsterdam を参照
パッケージマネージャー	pnpm	すべての Node.js/TypeScript プロジェクトのデフォルト

データベース選択

ニーズ	選択
標準 RDBMS	PostgreSQL
地理空間データ	PostgreSQL + PostGIS
ドキュメントストア	Azure Cosmos DB または MongoDB
レガシー/マイグレーション	Microsoft SQL Server

リポジトリ要件チェックリスト

要件	必須
アムステルダム市の GitHub 組織でホスト	はい
パブリックリポジトリ	はい（IaC = プライベートを除く）
チーム名を含む CODEOWNERS ファイル	はい
テンプレートセクションを含む README	はい
EU-PL v1.2 ライセンス	はい
develop と main のブランチ保護	はい
コミット署名（GPG または SSH）	はい
CI/CD パイプライン	はい
アーキテクチャ決定のための ADR	はい
変更履歴	はい

テストフレームワーク選択

コンテキスト	フレームワーク	カバレッジ目標
フロントエンド 単体/統合	Jest または Vitest + React Testing Library	70%
フロントエンド スナップショット	Jest または Vitest + react-test-renderer	—
フロントエンド E2E/リグレッション	Playwright または Cypress	—
フロントエンド API モック	MSW または Mirage JS	—
バックエンド（Django）	Django テストフレームワーク	80%
バックエンド（FastAPI）	pytest	80%

Git ワークフロー

ブランチモデル

• main — 安定した、本番環境で利用可能なコード
• develop — 統合ブランチ。デフォルトブランチとして設定
• 推奨: GitLab Flow、Git Flow、またはトランクベース（後者は CI/CD が必要）

ブランチ命名

パターン: <type>/<ticket>-<description>

プレフィックス	用途
feature/	新機能
chore/	メンテナンス、リファクタリング
bugfix/	バグ修正
hotfix/	本番環境の緊急修正
docs/	ドキュメントの変更

例:

• feature/PROJ-123-add-user-auth
• bugfix/PROJ-456-fix-login-redirect
• hotfix/fix-critical-payment-error

コミット形式

Conventional Commits を使用します。タイトル = 何を変更したか、説明 = なぜ変更したか。

feat(auth): add SSO integration for employees

Implements SAML-based SSO to replace legacy password login.
Reduces onboarding friction and improves security posture.

Refs: PROJ-789

ルール:

• アトミックコミット（1 コミットにつき 1 つの論理的な変更）
• GPG または SSH キーでコミットに署名する（SSH を推奨）
• コミットしてはならないもの: シークレット、認証情報、PII、生成されたファイル、node_modules、ローカル設定

ブランチ保護（必須）

• develop および main へのマージ前に PR レビューが必須
• 最低 1 名の承認
• 便宜のために無効化することはできない

完全なブランチ戦略、署名の設定、PR ワークフローについては、references/git-workflow.md をお読みください

セキュリティルール（概要）

#	ルール
1	要件・設計・アーキテクチャへのプロアクティブなセキュリティ統合
2	最小権限の原則
3	多層防御（複数のセキュリティ層）
4	フェイルセーフなデフォルト（障害発生時に安全な状態を維持）
5	攻撃面の最小化
6	サービスを信頼しない（すべての外部データを検証・サニタイズする）
7	オープン設計（機密性に依存しないセキュリティ）
8	デフォルトでセキュア
9	職務分離
10	セキュリティをシンプルに保つ

必須の実践:

• ブランチ保護ルールを有効化
• ソースコードを公開（IaC を除く）
• デプロイ前にコードをテスト
• サードパーティの依存関係を評価
• 市標準の認証およびモニタリング／ロギング
• RFC9068 に基づく JWT 検証（typ、issuer、audience、signature、expiration を検証）
• 転送中のすべてのデータに HTTPS を使用
• 取得するリソースに CSP ヘッダーと SRI を使用

コード例を含む完全なセキュリティチェックリストについては、references/security-checklist.md をお読みください

依存関係の評価

基準	確認事項
ドキュメント	品質、学習曲線、例
ライセンス	互換性はあるか？（MIT、Apache 2.0、BSD、EUPL = 安全）
パフォーマンス	バンドルサイズへの影響（特にフロントエンド）
セキュリティ	既知の脆弱性、パッチ対応時間
成熟度	プロジェクトの経過年数、ロードマップ、リリース頻度
メンテナンス	アクティブなメンテナー、コミット頻度
採用状況	ダウンロードの傾向（npm trends、PePy、Packagist）

ほとんどの基準でスコアが低いパッケージは拒否します。結果が混在している場合はチームに相談してください。

フロントエンドの追加要件:

• 定期的な更新とパッチ
• 品質、信頼性、必要性に関する年次レビュー
• セキュリティスキャン: GitHub Dependabot、NPM audit、Snyk

アクセシビリティ

必須: デジタル政府法に基づく WCAG 2.1 AA 準拠。

すべての政府ウェブサイト、アプリ、イントラネット、エクストラネット、クラウドアプリ、モバイルアプリに適用されます。

主な要件:

• 200% ズームのサポート
• 説明的なリンクテキスト
• スクリーンリーダー対応
• 論理的なページ／フォーカス順序、表示されるフォーカスリング
• マルチメディアのキャプション
• WCAG 1.4.12 に基づく CSS スペーシング
• 右から左への言語のサポート

テストツール: WebAIM WAVE、W3C Markup Validation、Google Lighthouse、VoiceOver、JAWS、TalkBack。

データベース標準

• PostgreSQL がすべての新規プロジェクトのデフォルト RDBMS です
• 地理空間データには PostGIS 拡張機能を使用
• ローカル開発には公式 Docker イメージ（postgres、postgis/postgis）を使用
• バージョンは Azure PostgreSQL Flexible Server に合わせる

Docker 標準

• 開発、テスト、本番環境でのコンテナ化には Docker を使用する
• ベースイメージ: 適切にメンテナンスされているもの、正確なバージョンを指定する（latest タグは決して使用しない）
• 一般的に承認されているイメージ: Alpine、NGINX、Node.js、PHP、Postgres、Python、Ubuntu
• 必要なパッケージのみをインストールする
• すべての依存関係のバージョンを明示的に指定する
• Dockerfile はアプリの GitHub リポジトリに置く
• コンパイル済みイメージは Azure Container Registry（ACR）に置く
• 定期的な更新（最低でも月次または四半期ごと）
• DTAP/OTAP 環境ごとに別々のイメージを作成しない
• 非公式または未認定の Docker イメージを使用しない
• 機密データには環境変数を使用する（ハードコードは決してしない）

パッケージマネージャーとプロジェクト構成

• pnpm は、すべての新規 Node.js/TypeScript プロジェクトにおけるデフォルトのパッケージマネージャーです。npm または yarn を使用するには、明示的な正当性（例: ツールの非互換性、クライアントの制約）が必要です
• package.json の packageManager フィールドで pnpm のバージョンを固定するには、corepack enable を使用します

モノレポを採用すべき場合

シグナル	構成
共有ライブラリのない単一のデプロイ可能なアプリ	単一パッケージ
コードを共有する複数のアプリ（例: フロントエンド + API + 共有型）	pnpm モノレポ
チーム間で共有されるデザイントークン、UI ライブラリ、または設定	pnpm モノレポ
共有コードのない独立したマイクロサービス	別々のリポジトリ

モノレポのセットアップ

# pnpm-workspace.yaml
packages:
  - "apps/*"
  - "packages/*"

標準的なディレクトリ構成:

├── apps/
│   ├── web/              # Next.js frontend
│   └── api/              # Backend service
├── packages/
│   ├── shared/           # Shared types, utils
│   └── config/           # Shared ESLint, TSConfig
├── pnpm-workspace.yaml
├── package.json          # Root with "packageManager" field
└── pnpm-lock.yaml

パッケージ間参照

// apps/web/package.json
{
  "dependencies": {
    "@project/shared": "workspace:*"
  }
}

パッケージをまたいでコマンドを実行: pnpm -r build、pnpm --filter web dev。

ドキュメント要件

すべての新規リポジトリに必須（2024年5月以降）:

1. アプリケーションの概要（目的）
2. ライセンス: EU-PL v1.2
3. README（標準テンプレートを使用）
4. アーキテクチャ決定記録（ADR）
5. レビュー日付を含む変更履歴
6. データ処理に関する情報
7. API ドキュメント（エンドポイント、パラメータ、認証、リクエスト/レスポンス）
8. 目的を含む機能一覧

README テンプレートと ADR テンプレート: references/project-setup-checklist.md を参照してください

すべきこと / すべきでないこと

すべきこと	すべきでないこと
すべての新規フロントエンドに TypeScript を使用する	型のない JavaScript を使用する
デフォルトのデータベースとして PostgreSQL を使用する	正当性なくデータベースを選定する
GPG または SSH でコミットに署名する	署名なしのコミットをプッシュする
マージ前に PR レビューを必須とする	レビューなしでマージする
EU-PL v1.2 ライセンスを使用する	承認なく他のライセンスを使用する
WCAG 2.1 AA 準拠	アクセシビリティに非対応の機能をリリースする
公開リポジトリ（IaC を除く）	正当性なくプライベートリポジトリにする
基準に照らして依存関係を評価する	評価なしでパッケージを追加する
バージョンタグを固定した Docker	latest タグまたは未認定イメージを使用する
初日からセキュリティ・バイ・デザイン	後付けでセキュリティを追加する
Conventional Commits 形式	文脈のないコミットメッセージ
フロントエンド 70% / バックエンド 80% のカバレッジ	本番コードのテストを省略する
シークレットを Key Vault / 環境変数に保存する	シークレットをハードコードしたり認証情報をコミットしたりする
README、ADR、変更履歴で文書化する	リポジトリを未文書化のままにする
Node.js/TypeScript プロジェクトに pnpm を使用する	正当性なく npm または yarn を使用する

共有コンポーネント

コンポーネント	リポジトリ
Amsterdam Design System	github.com/Amsterdam/design-system
BMI DMS Upload	github.com/Amsterdam/bmi-dms-upload
Wonen UI	github.com/Amsterdam/wonen-ui
Maps	maps.developers.amsterdam

スキル間の境界

関心事	このスキル	他のスキル
どのフレームワーク/言語を使用するか	developers-amsterdam	—
UI コンポーネントの構築方法	—	amsterdam-design-system
テキストコンテンツとトーン・オブ・ボイス	—	amsterdam-stijl

参照ファイル

ファイル	読むタイミング
references/tech-stack.md	言語、フレームワーク、共有コンポーネントを選定するとき。逸脱を正当化するとき
references/git-workflow.md	ブランチの設定、コミット署名、PR ワークフロー、Git プラクティスのレビューを行うとき
references/testing-standards.md	テストインフラをセットアップするとき、フレームワークを選定するとき、カバレッジ目標を定義するとき
references/security-checklist.md	認証、JWT 検証、CSP、Docker セキュリティを実装するとき、セキュリティをレビューするとき
references/project-setup-checklist.md	新しいリポジトリを作成するとき、README/ADR を書くとき、ライセンスを設定するとき