Potola Coding Rules

1. 目的

本ドキュメントは、Potola におけるコーディングルールを定義する。

目的は、

コード品質を統一する
保守性を向上する
AI Coding Agent の出力品質を安定させる
レビューコストを削減する

ことである。

AI Coding Agent は、本ドキュメントをコード記述上の正本として扱う。

AI の作業手順、権限、Scope 制御、ドキュメント読み込みルールは AGENTS.md に従う。

技術構成・設計境界は 01-architecture.md、ファイルやディレクトリの配置は 02-repository-structure.md を正本とする。

2. 基本原則

2.1 読みやすさを優先する

短いコードよりも理解しやすいコードを優先する。

禁止例

const x = a ? b : c;

推奨例

let result;

if (condition) {
  result = valueA;
} else {
  result = valueB;
}

2.2 明示的であること

暗黙的な挙動を避ける。

型、責務、意図が分かるコードを書く。

2.3 シンプルであること

過度な抽象化を行わない。

将来使うか分からない汎用化は避ける。

2.4 正本ドキュメントとの責務を分離する

本ドキュメントは「コードをどう書くか」を定義する。

以下は本ドキュメントでは重複して定義しない。

プロダクト判断 → 00-potola-philosophy.md
技術構成・設計境界 → 01-architecture.md
ファイル・ディレクトリ配置 → 02-repository-structure.md
PoC・技術実験 → 03-poc-and-experiments.md
AI の作業手順・権限・Scope 制御 → AGENTS.md

3. TypeScript

必須

strict: true

any禁止

禁止

const user: any

推奨

type User = {
  id: string;
  name: string;
};

型推論できない場合は明示する

推奨

const photos: Photo[] = [];

unknown を優先する

禁止

catch (error: any)

推奨

catch (error: unknown)

4. 命名規則

コンポーネント

PascalCase

PhotoCard.svelte
AlbumGrid.svelte

関数

camelCase

createAlbum()
uploadPhoto()
publishAlbum()

定数

UPPER_SNAKE_CASE

MAX_UPLOAD_SIZE
DEFAULT_PAGE_SIZE

DBカラム

snake_case

owner_user_id
created_at
updated_at

テーブル名

複数形

users
photos
albums
album_photos

boolean

is has can

を利用する

isPublic
hasThumbnail
canEdit

5. コードの責務分離

ファイルやディレクトリの具体的な配置は 02-repository-structure.md と既存実装に従う。

本セクションでは、配置場所ではなくコード上の責務のみを定義する。

UI Component

UI Component は表示とユーザー操作の受け渡しを主責務とする。

原則として、以下を直接担当しない。

DB 更新
認証・認可の最終判定
R2 操作
Infrastructure 固有の処理

Service / Application Logic

外部サービスとの通信や、複数処理を組み合わせる Application Logic は、UI から分離する。

責務が分かる名前を使用する。

例:

albumService
photoService
authService

Data Access

DB や Storage などの Data Access は、UI から分離する。

SQL や Infrastructure 固有の処理を Component に直接記述しない。

Types

型は、その型を所有する Feature または Domain の近くに置く。

複数領域で本当に共有される型の配置は 02-repository-structure.md に従う。

Utility

Utility は明確な責務を持つ純粋関数を基本とする。

「将来使うかもしれない」という理由で Generic Utility を先行して作らない。

6. 関数設計

1関数1責務

禁止

createAlbumAndUploadPhotosAndPublish()

推奨

createAlbum()
uploadPhoto()
publishAlbum()

関数名は動詞で始める

推奨

getAlbum()
createAlbum()
deleteAlbum()

副作用を明確にする

推奨

savePhoto()

禁止

handlePhoto()

7. エラー処理

try-catch を使用する

推奨

try {
  await repository.save();
} catch (error) {
  logger.error(error);
}

APIレスポンス形式を統一する

type ApiResponse<T> = {
  success: boolean;
  data?: T;
  error?: {
    code: string;
    message: string;
  };
};

内部エラーを公開しない

禁止

return error.stack;

ログへ出力する

推奨

logger.error(error);

8. 非同期処理

async / await を使用する

禁止

.then()
.catch()

推奨

await photoRepository.save();

Promise.all を活用する

独立処理は並列化する。

9. データアクセス

UIから直接DBアクセス禁止

禁止

Svelte Component
↓
Supabase DB

推奨

Component
↓
Service
↓
API
↓
Repository
↓
DB

SQLはRepositoryへ集約

禁止

Component内SQL

10. 認証

APIで認可確認

禁止

UIだけで権限制御

所有者確認必須

写真

アルバム

更新

削除

公開

の操作では所有者確認を行う。

11. R2

Object Key をハードコードしない

禁止

users/123/photo.jpg

推奨

generatePhotoObjectKey()

URLを直接保存しない

推奨

r2_object_key

を保存する。

12. コメント

なぜを書く

禁止

// albumを保存する
saveAlbum();

推奨

// 公開URL生成前にAlbum IDを確定させる
saveAlbum();

自明なコメント禁止

コードで分かる内容は書かない。

13. テスト

受け入れテストを重視する。

重要ロジックはテスト対象とする。

例

公開URL生成
権限チェック
画像変換ジョブ

各開発段階で必要となる具体的なテスト範囲は、現在のScopeおよびIssueで定義する。

14. AI Coding Agent との関係

AI Coding Agent の Workflow、Permission、Scope Control、Self Review は AGENTS.md を正本とする。

本ドキュメントでは、AI 固有の作業手順を重複して定義しない。

AI Coding Agent も人間の開発者と同じ Coding Rules に従う。

15. コードレビュー基準

レビューでは以下を確認する。

要件を満たしているか
Scope外実装がないか
型安全か
エラー処理があるか
所有者チェックがあるか
セキュリティ問題がないか
命名と責務が明確か
不要な抽象化や未使用コードがないか

16. まとめ

Potola のコードは、

読みやすくシンプルで型安全で AIが理解しやすい

ことを最優先とする。

高度な設計よりも、長期間保守できるコードを重視する。

作成日　2026.09.09