---
title: 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 読みやすさを優先する

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

禁止例

```ts
const x = a ? b : c;
```

推奨例

```ts
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

### 必須

```ts
strict: true
```

---

### any禁止

禁止

```ts
const user: any
```

推奨

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

---

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

推奨

```ts
const photos: Photo[] = [];
```

---

### unknown を優先する

禁止

```ts
catch (error: any)
```

推奨

```ts
catch (error: unknown)
```

---

## 4. 命名規則

### コンポーネント

PascalCase

```ts
PhotoCard.svelte
AlbumGrid.svelte
```

---

### 関数

camelCase

```ts
createAlbum()
uploadPhoto()
publishAlbum()
```

---

### 定数

UPPER_SNAKE_CASE

```ts
MAX_UPLOAD_SIZE
DEFAULT_PAGE_SIZE
```

---

### DBカラム

snake_case

```sql
owner_user_id
created_at
updated_at
```

---

### テーブル名

複数形

```sql
users
photos
albums
album_photos
```

---

### boolean

is
has
can

を利用する

```ts
isPublic
hasThumbnail
canEdit
```

---

## 5. コードの責務分離

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

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

### UI Component

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

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

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

### Service / Application Logic

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

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

例:

```ts
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責務

禁止

```ts
createAlbumAndUploadPhotosAndPublish()
```

推奨

```ts
createAlbum()
uploadPhoto()
publishAlbum()
```

---

### 関数名は動詞で始める

推奨

```ts
getAlbum()
createAlbum()
deleteAlbum()
```

---

### 副作用を明確にする

推奨

```ts
savePhoto()
```

禁止

```ts
handlePhoto()
```

---

## 7. エラー処理

### try-catch を使用する

推奨

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

---

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

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

---

### 内部エラーを公開しない

禁止

```ts
return error.stack;
```

---

### ログへ出力する

推奨

```ts
logger.error(error);
```

---

## 8. 非同期処理

### async / await を使用する

禁止

```ts
.then()
.catch()
```

推奨

```ts
await photoRepository.save();
```

---

### Promise.all を活用する

独立処理は並列化する。

---

## 9. データアクセス

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

禁止

```ts
Svelte Component
↓
Supabase DB
```

推奨

```text
Component
↓
Service
↓
API
↓
Repository
↓
DB
```

---

### SQLはRepositoryへ集約

禁止

```ts
Component内SQL
```

---

## 10. 認証

### APIで認可確認

禁止

```ts
UIだけで権限制御
```

---

### 所有者確認必須

写真

アルバム

更新

削除

公開

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

---

## 11. R2

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

禁止

```ts
users/123/photo.jpg
```

推奨

```ts
generatePhotoObjectKey()
```

---

### URLを直接保存しない

推奨

```ts
r2_object_key
```

を保存する。

---

## 12. コメント

### なぜを書く

禁止

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

推奨

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

---

### 自明なコメント禁止

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

---

## 13. テスト

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

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

例

```ts
公開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