katachi

Kotlin architecture test

Deny by default

katachi で
動くアーキテクチャドキュメントを

宣言していないファイルは、存在を許されない。プロジェクト全体の「どこに何を置けるか」を Kotlin DSL で書き、テストとして検証します。

導入する →

GitHub ↗

ProjectArchitecture.kt

val projectArchitecture = architecture {
  "domain".group {
    "UseCase" {
      layout {
        "core/domain" / mainSourceSet / kotlin /
          "com/example/core/domain/useCase" / "*UseCase".ktFile()
      }
    }
  }
}

崩れるのは
いつも1ファイルから。

置き場所の逸脱は、レビューで見逃しがちです。AI Agent がファイルを作るときも、手本にするのは文書ではなく既存の配置。1つずれれば、そこから複製されていきます。

ドキュメントには、強制力がない。

src/main/kotlin/com/example/

├─ useCase/
│  ├─ GetUserUseCase.kt
│  └─ UpdateUserUseCase.kt
├─ DeleteUserUseCase.kt  ← 置き場所が違う
└─ misc/
   └─ memo.md            ← 役割がない

この2つを、誰も検査していない

ProjectArchitecture.kt が許可した範囲

src/main/kotlin/com/example/
├─ useCase/*UseCase.kt       ✓ declared
├─ repository/*Repository.kt ✓ declared
├─ DeleteUserUseCase.kt      ✕ reported
└─ misc/memo.md              ✕ reported

● 宣言済み　● 違反として報告される

宣言した場所だけが
存在を許される

katachi では、存在してよいものを宣言します。禁止を数え上げるのではありません。

Deny by default — 宣言にないものは、存在できない。

宣言にないファイルは
アーキテクチャ違反

禁止を数え上げる運用から、存在してよいものを宣言する運用へ。「いつの間にか増えた置き場所」が起きません。

"UseCase" { layout { "domain/useCase" / "*UseCase".ktFile() } }
// domain/useCase/Helper.kt → [UnexpectedFile]

Role 駆動による
アーキテクチャ定義

1つの Role が2つのモジュールに住んでいても、説明は1箇所のまま。置き場所は layout { } を並べて宣言します。

"UseCase" {
  summary = "各画面で発生するアプリ固有の1つの振る舞い"
  layout { "core/domain/useCase" / "*UseCase".ktFile() }
  layout { "feature/home/useCase" / "*UseCase".ktFile() }
}

検査した定義が、
そのままドキュメントへ

title / summary / example を Role の中に書きます。v0.2 からは ./gradlew katachiDocs で、同じ定義からドキュメントを生成できます。

"UseCase" {
  title = "ユースケース"
  summary = "各画面で発生するアプリ固有の1つの振る舞い"
  example("GetUserUseCase", "ユーザーを取得する")
}

Deny.Role.Docs.

Built for AI agents.
Good for humans too.

エージェントにとって有効なのは、文章ではなく落ちるテストです。

あなたのプロジェクトの形を、宣言してみる。

プロジェクト全体の構成を定義し、テストを実行しましょう。宣言にないファイルは違反として報告されます。

導入する →定義を作り、テストを通すまでの手順。

設計思想を読む →なぜ deny by default なのか、Konsist との住み分け。

GitHub ↗実装とロードマップ。