writing-tech-specs

技術仕様書の作成

目的

変更内容を説明する簡潔で軽量な技術仕様書を作成します。PlantUML 図と簡潔な説明を使用します。仕様書では実装の詳細ではなく、変更内容に焦点を当てます。

使用する場面

• ユーザーが「tech spec」「technical specification」「tech-spec」を依頼した場合
• ユーザーが「create spec」「write spec」「implementation spec」と言及した場合
• 実装前に機能変更を文書化したい場合
• チーム内で設計上の決定事項を共有したい場合

プロセス

1. 要件を収集する

必要な詳細をユーザーに尋ねます。わからないことがあれば、一緒に整理します。

• 機能／タスクのタイトル：何を構築または変更しますか？
• スコープ：どのサービスに影響しますか？（node-core、node-auth、frontend など）
• 主な変更点：
  • 新規または変更された API エンドポイント
  • データベーススキーマの変更（新しいテーブル、カラム）
  • 新規または変更された業務フロー
  • フロントエンドの変更（画面、コンポーネント）

2. 仕様書の構成を作成する

次のテンプレート構成を使用します。

# [tech-spec] <Title>

* 1 [Infrastructure](#Infrastructure)
  * 1.1 [<service-name>](#<service-name>)
* 2 [Model](#Model)
  * 2.1 [<service-name>](#<service-name>)
    * 2.1.1 [<EntityName>](#<EntityName>)
* 3 [Flow](#Flow)
  * 3.1 [Backend](#Backend)
    * 3.1.1 [<service-name>](#<service-name>)
* 4 [Happy path](#Happy-path)
* 5 [Backwards compatibility](#Backwards-compatibility)

# Infrastructure

## <service-name>

<API endpoints, permissions, cron jobs>

# Model

## <service-name>

### <EntityName>

<PlantUML class diagram in code block>

# Flow

## Backend

### <service-name>

<PlantUML activity/sequence diagram in code block>

# Happy path

<Brief description or test scenarios>

# Backwards compatibility

<Notes if applicable, omit if not needed>

3. セクションを作成する

インフラストラクチャセクション

API エンドポイントを簡単な説明とともに列挙します。

* POST /users/me/terms-and-conditions/latest/accept
  * response `{"successful": true}`

または、リクエストボディを含めます。

* PATCH /tenant-benefits/:tenantBenefitId/order
  * body: { direction: up/down }

モデルセクション

コードブロック内の PlantUML クラス図を使用します。既存の変更されないフィールドには ... を使用します。

### Appointment

@startuml class Appointment { ... status: string [enum: scheduled, in_progress, completed] } @enduml

新しいテーブルの場合は、すべてのフィールドを列挙します。

### IntegrationMapping (new table)

@startuml class IntegrationMapping { id: uuid integrationSystem: enum type: string key: string value: string } @enduml

フローセクション

バックエンドのフローには、コードブロック内の PlantUML アクティビティ図を使用します。

### Claim item correct/incorrect flow

@startuml () --> "Claim Submitted for Review" #lightblue if "Is correct?" then --> [Yes] "Update correct fields" --> () else --> [No] "Update incorrect fields" --> "Returned to Patient" #lightblue --> (*) @enduml

サービス間の通信にはシーケンス図を使用します。

@startuml actor "User" as user participant "Service A" as a participant "Service B" as b user -> a: Request a -> b: Call b --> a: Response a --> user: Result @enduml

ハッピーパスセクション

簡単な説明またはテストシナリオを記載します。

Check that the user cannot use the app if he doesn't accept the latest T&C.
After accepting, the user should be able to use the app with no restrictions.

または、箇条書きにします。

* Check if an appointment can be flagged for did-not-attend successfully.
* Verify that an error is thrown when trying to flag a cancelled appointment.

後方互換性セクション

必要な場合にのみ記載します。簡潔にまとめます。

Migration: Create repository records from unique combinations, then add FK.

4. 保存して出力する

• 必要に応じてディレクトリを作成します：mkdir -p resource/tech-spec
• resource/tech-spec/<tech-spec-title>.md に書き込みます（kebab-case を使用）
• ファイルパスをユーザーに返します

重要なルール

次のルールに従い、仕様書を焦点の定まった読みやすいものにします。

1. ファイル構成の比較はしない — 仕様書では変更内容を記述し、ファイルの配置場所は記述しません
2. ファイルマッピング表は作成しない — これは実装の詳細であり、仕様ではありません
3. インポート更新の方針は記載しない — これは仕様書ではなく、実装に属する内容です
4. コード例は記載しない — PlantUML 図のほうが汎用的で、特定の言語に依存しません
5. チェックリストは作成しない — チェックリストはタスクやストーリー向けです。仕様書ではシステムの状態を記述します
6. 実装手順を段階的に記載しない — 仕様書では「何を」記述し、「どのように」は記述しません
7. 簡潔にまとめる — 各項目は1～2文とし、複雑なフローには図を使用します
8. PlantUML にはコードブロックを使用する — 可読性と書式が向上します

スコープの指針

仕様書が大きくなりすぎた場合は、分割を検討します。

• 影響を受けるサービスが3つを超える場合：サービスごとに仕様書を分けることを検討します
• モデルの変更が8件を超える場合：ドメインごとに分割することを検討します
• 複雑なフローが4つを超える場合：ユーザージャーニーごとに分割することを検討します

例

最小限の仕様書

# [tech-spec] Custom order for tenant benefits

* 1 [Infrastructure](#Infrastructure)
  * 1.1 [node-core](#node-core)
* 2 [Model](#Model)
  * 2.1 [node-core](#node-core.1)

# Infrastructure

## node-core

* PATCH /tenant-benefits/:tenantBenefitId/order
  * body: { direction: up/down }

# Model

## node-core

@startuml class TenantBenefit { ... order: number } @enduml

フローを含む仕様

# [tech-spec] Claim item locking

* 1 [Model](#Model)
  * 1.1 [node-core](#node-core)
* 2 [Flow](#Flow)
  * 2.1 [Backend](#Backend)
* 3 [Happy path](#Happy-path)

# Model

## node-core

### ReimbursementClaimItem

@startuml class ReimbursementClaimItem { ... incorrectAt?: number incorrectById?: string incorrectReason?: string correctAt?: number correctById?: string } @enduml

# Flow

## Backend

### Claim item correct/incorrect flow

@startuml () --> "Claim Submitted for Review" #lightblue if "Is correct?" then --> [Yes] "Update correct fields" --> () else --> [No] "Update incorrect fields" --> "Returned to Patient" #lightblue --> (*) @enduml

# Happy path

Advisor marks claim items as correct/incorrect. Patient sees which items need correction.

セクションリファレンス

セクション	含める条件	内容
インフラストラクチャ	新規または変更されたエンドポイント、cron、権限	API の概要
モデル	データベーススキーマの変更	PlantUML クラス図
フロー	新規または変更されたビジネスロジック	PlantUML アクティビティ図／シーケンス図
ハッピーパス	常に	簡単な説明またはテストシナリオ
下位互換性	破壊的変更	移行に関する注意事項
デプロイ	特別なデプロイ要件	必要な場合のみ

その他の例

完全な仕様の参考例については、./examples フォルダーをご覧ください。以下を網羅しています。

• API 設計パターン
• サービス間通信
• 複雑な状態機械
• フロントエンドのフロー