queryspec は feature 所有とし、feature 間共有を推奨しない方針を明文化する

[mk3008]

Summary

ztd-cli / VSA の設計原則として、queryspec は共有部品ではなく、その feature が所有する DB 境界仕様であることを明文化したい。

本件では、feature をまたいだ queryspec の共通化を推奨しない方針を guide / README / scaffold philosophy に反映する。
似た SQL や似た queryspec が複数 feature に存在することは許容し、修正箇所の探索は query grep 系の支援で補う。

Background

実務では、たとえば売上追加 feature と売上更新 feature のように、見た目がよく似た query が複数 feature に現れることがある。

例:

• 売上追加 feature における売上明細 insert
• 売上更新 feature における、存在判定後の売上明細 insert 相当処理

このとき、queryspec を別 feature から import して共有したくなる可能性がある。
ただし queryspec は単なる SQL 部品ではなく、その feature に属する DB 境界仕様であり、配置された文脈によって将来的な変更点や責務が分岐しやすい。

共通化には以下の懸念がある。

• 完全な同一性を長期にわたり保証しにくい
• 所有者が曖昧になり、変更判断が難しくなる
• 影響範囲が不明確になりやすい
• feature ごとの責務分離が崩れやすい

そのため、VSA の原則としては DRY より所有境界の明確さを優先したい。

Proposal

以下の方針を明文化する。

1. queryspec は feature 所有とする

• queryspec は共有ライブラリではなく、その feature の DB 境界仕様として扱う
• feature をまたいで queryspec を import して再利用しない
• 類似した queryspec が複数 feature に存在することは許容する

2. 類似性は共有理由にならない

• SQL が似ている
• DTO が似ている
• 一時点で処理内容が同じに見える

といった構造的類似性は、共有 ownership の根拠にしない。

3. 重複による修正箇所増加は許容する

修正箇所が増えることはデメリットとして認めるが、以下を優先する。

• feature 所有の明確さ
• 変更影響範囲の局所化
• 将来的な差分進化への追従しやすさ

4. 修正漏れ対策は query grep で支援する

重複による修正漏れは、feature 間共有ではなく query grep / SQL grep / 類似 query 発見支援で補う方針とする。

Non-Goals

本件では、feature 非依存の純粋 utility まで禁止対象にはしない。

たとえば以下のようなものは、必要に応じて共有してよい。

• 文字列整形
• 日付変換
• 純粋関数として独立した補助処理
• DB 境界仕様そのものではない補助ロジック

禁止対象は、feature の DB 境界仕様としての queryspec の feature 間共有である。

Acceptance Criteria

• guide / README / philosophy 文書に、queryspec は feature 所有であることが明記されている
• feature 間で queryspec を共有しない方針が明記されている
• 類似 SQL を理由に共有しないことが明記されている
• 修正箇所増加の代償を query grep 支援で補う方針が明記されている
• 必要なら scaffold / guide のサンプルでも、feature ごとに queryspec を持つ構造が示されている

Example

売上追加 feature:

features/
  sales-create/
    spec.ts
    queries/
      insert-sales-header/
        spec.ts
        query.sql
      insert-sales-detail/
        spec.ts
        query.sql

売上更新 feature:

features/
  sales-save/
    spec.ts
    queries/
      upsert-sales-header/
        spec.ts
        query.sql
      insert-sales-detail/
        spec.ts
        query.sql

補足

Related to #717

このとき insert-sales-detail/ が結果的に似た SQL を持っていても、両者は別 feature の所有物として扱う。

Why It Matters

この方針により、以下を得られる。

• feature ごとの ownership が明確になる
• 変更影響範囲が読みやすくなる
• 将来的に似た query が分岐しても破綻しにくい
• "共有したがゆえの広域影響" を避けやすくなる
• AI / 人間の双方に対して、どこを直すべきかを説明しやすくなる

補足

Related to #717