この記事は約 4 分で読めます。

筆者プロフィール: ソフトウェアエンジニア。「知った気にならない。いつまでも学び続ける」を信条に、業務と個人開発の両輪で技術を磨いています。AI 駆動開発で複数の個人開発アプリを構築・運用中。
👉 ポートフォリオ: 筆者ホームページ

機能追加には DB 変更 / Service / API / UI / テスト / docs / マトリクス更新 の横断作業が必要。本記事では、運用中の SaaS 「たすきば Knowledge Relay」 で使っている 5 領域 × 14 項目の手順書 を整理します。

サービスの機能紹介・画面イメージ・コンセプトは公式プロダクトページをご覧ください。
👉 たすきば Knowledge Relay — 公式プロダクトページ

5 領域の標準手順

領域 1: テーマ / UI 配色

1. src/config/theme-definitions.ts に色定義を追加
2. tailwind.config.ts の colors に反映
3. Light / Dark テーマで両方確認
4. Visual Regression baseline 確認

領域 2: マスタデータ追加

1. src/config/master-data.ts に定数追加
2. Prisma schema の enum (該当する場合) を更新
3. 業務用語辞書 (GLOSSARY.md) に追記
4. UI のセレクタに反映
5. テストを追加

領域 3: 画面追加 (page.tsx)

1. src/app/(dashboard)/xxx/page.tsx を作成
2. Server Component で実装
3. Service 層から context (viewerTenantId, viewerUserId) で呼び出し
4. PERMISSION_MATRIX.md に行追加
5. docs/test/E2E_COVERAGE.md に追記
6. E2E spec を書く
7. UI_PATTERNS.md を参照して見た目を統一

領域 4: DB スキーマ変更

1. prisma/schema.prisma を編集
2. pnpm prisma migrate dev で migration 生成
3. 生成された SQL を確認
4. DATA_MODEL.md を更新
5. 後方互換性を確認 (N-9)
6. Service 層のテスト追加
7. main から rebase してから PR

領域 5: i18n (将来)

1. src/locales/{ja,en}/xxx.json に文言追加
2. キー名は階層的に
3. 各言語に翻訳追加
4. UI コンポーネントで t('xxx') を使う
5. テストで複数言語を verify

横断 14 項目チェックリスト

機能追加 PR で、必ず確認する横断項目:

□ Service 層に viewerTenantId 必須引数
□ 認可チェック (checkProjectPermission 等)
□ DB クエリに tenantId フィルタ + deletedAt: null
□ Zod schema を src/lib/validators/ に追加
□ src/config/ に定数集約
□ UI = API 認可一致
□ 単体テスト追加
□ 統合テスト追加
□ E2E spec 追加 + E2E_COVERAGE.md に記載
□ PERMISSION_MATRIX.md 更新
□ FEATURE_CATALOG.md に追加
□ 必要なら ADR を書く
□ 必要なら KDD を書く
□ Visual Regression baseline 再生成 (UI 変更時)

PR テンプレートに含めて、機械的に確認。

AI 駆動での機能追加

私: 「ナレッジに添付ファイル機能を追加してください。
     HOW_TO_ADD_FEATURES の手順に従ってください。」

Claude: 「以下の流れで進めます:
  1. Prisma schema に Attachment テーブル追加
  2. migration 生成
  3. attachment.service.ts 実装 (viewerTenantId 必須)
  4. API Route /api/attachments
  5. UI: AttachmentList コンポーネント
  6. 単体 / 統合 / E2E テスト
  7. PERMISSION_MATRIX.md / FEATURE_CATALOG.md 更新

  順次実装します。」

手順書を参照することで、AI も漏れなく実装。

機能追加の難易度別戦略

規模	タスク数	戦略
小 (1-5)	数時間	1 PR で完結
中 (5-15)	数日	1 PR or 2 PR
大 (15-30)	1 週間+	仕様 PR + 実装 PR
超大 (30+)	数週間	必ず分割

30+ タスクは 1 PR で収まらない、必ず分割する。

リリース直前の機能追加禁止

リリース 2 週間前以降、新機能追加は禁止。

期間	許可される変更
直前 2 週間	バグ修正 / docs / セキュリティパッチのみ
リリース後	新機能再開

リリース直前の機能追加は事故の元。新機能は次の Phase に。

段階的リリース (feature flag)

大きな機能は、段階的にリリース。

Phase	公開範囲
A	feature flag で hidden (ユーザに見えない、テスト可)
B	一部ユーザに公開 (beta)
C	全ユーザに公開

Phase ごとに検証することで、安全に拡大。

機能追加後の振り返り

機能追加後、振り返りを実施。

□ 想定したユーザ価値が出ているか?
□ バグは発生していないか?
□ パフォーマンスへの影響は?
□ ロードマップへのフィードバック

「追加して終わり」にしない。継続的に改善する文化。

おわりに

領域	主要手順
テーマ / UI 配色	config 集約 + Visual 確認
マスタデータ	config + 業務用語辞書
画面追加	Server Component + マトリクス更新
DB スキーマ	migration + 後方互換
i18n	locales + テスト (将来)

手順書で構造化することで、機能追加の品質が安定 します。

本記事の手順書は、運用中の SaaS 「たすきば Knowledge Relay」 で実装しています。
👉 たすきば Knowledge Relay — 公式プロダクトページ