初めてのアーキテクチャ定義

katachi が必要かどうか迷う場合は、先に モチベーション を読むことをおすすめします。

katachi をプロジェクトに導入する

AI Agent に任せる

1. お使いの AI Agent を起動し、次のように プロンプトを入力 してください。

   このプロジェクトに katachi を導入してください。
   
   - https://tbsten.github.io/katachi/install/ja/index.md に従って導入してください。

   • 事前にプロジェクトを git で管理しておくことをおすすめします。
   • AI Agent が参照するページには、プロジェクトへの katachi の導入を あなたと一緒に 進めるよう指示が書いてあります。
   追加のオプション

   • アーキテクチャに関するドキュメントがコードベースの外にある場合 （例: Notion で管理しているなど）、プロンプトにそのリンクを含めてください。
   • AI Agent は、デフォルトでは architecture-test モジュールを作り、そこにアーキテクチャ定義を書こうとします。
     • 別のモジュールに作成したい場合 は テストは <module> に作成してください のようなプロンプトを追加してください。
   • context 管理の一環として、katachi 導入専用のセッションを新規に開始する ことをおすすめします。
     • Claude Code, Codex CLI の場合: /clear コマンドでセッションをクリアしてからプロンプトを入力します。

2. AI Agent がプロジェクトにセットアップした差分を レビュー し、必要に応じて内容を修正してください。

   注目すべき点:

   • architecture-test/src/test/kotlin/<パッケージ>/ProjectArchitecture.kt がエントリーポイントです。
   • AI Agent は architecture の定義を group・Role ごとのファイルに分け、ProjectArchitecture.kt の下のパッケージに置きます。そのファイルもレビュー対象です。
   • チームで開発している場合は、チームメンバー（特にチームのリード）にも重点的にレビューしてもらいましょう。

3. アーキテクチャテストを実行 し、All green になることを確認してください。

   ./gradlew :architecture-test:test

   これでセットアップは完了です。

手動でインストールする

1. :architecture-test モジュールを作る

   アプリのどの層にも属さない、アーキテクチャ定義とそれを検査するテストだけを置くモジュールです。

   settings.gradle.kts

   pluginManagement {
       repositories {
           gradlePluginPortal()
           mavenCentral()
       }
   }
   
   include(":architecture-test")

   katachi の Gradle plugin は Gradle Plugin Portal ではなく Maven Central に公開しています。pluginManagement { } に mavenCentral() が無いと、plugin を解決できません。

2. 依存を書く

   プロジェクトが Android でも KMP でも、ここはプレーンな kotlin("jvm") モジュールにします。katachi 自身が JVM のライブラリだからです。

   architecture-test/build.gradle.ktsShow moreShow less

   import org.gradle.api.tasks.testing.logging.TestExceptionFormat
   
   plugins {
       kotlin("jvm") version "<Kotlin のバージョン>"
       id("me.tbsten.katachi") version "<katachi のバージョン>"
   }
   
   kotlin {
       jvmToolchain(17)
   }
   
   tasks.test {
       useJUnitPlatform()
       // 検査するファイルは Test タスクの入力ではないので、毎回走らせる（ビルドキャッシュにも結果を書かせない）
       outputs.upToDateWhen { false }
       outputs.cacheIf { false }
       // 違反の一覧をコンソールに出す
       testLogging { exceptionFormat = TestExceptionFormat.FULL }
   }
   
   dependencies {
       testImplementation("me.tbsten.katachi:katachi:<katachi のバージョン>")
       testImplementation("me.tbsten.katachi:katachi-konsist:<katachi のバージョン>")
       testImplementation(platform("org.junit:junit-bom:5.14.4"))
       testImplementation("org.junit.jupiter:junit-jupiter")
       testRuntimeOnly("org.junit.platform:junit-platform-launcher")
   }
   
   katachi {
       architecture = "com.example.projectArchitecture"
   }

   Show moreShow less
   • outputs.upToDateWhen { false } / outputs.cacheIf { false }: katachi が検査するのはリポジトリ全体のファイルですが、Gradle が Test タスクの入力として見ているのはテストのクラスパスだけです。これが無いと、ファイルを足したり変えたりしても :architecture-test:test が UP-TO-DATE で飛ばされ、違反があっても緑のままになります。cacheIf は、ビルドキャッシュを有効にしているときに前の結果が使い回されないようにするための指定です。
   • testLogging { exceptionFormat = TestExceptionFormat.FULL }: これが無いと、テストが落ちてもコンソールには例外のクラス名の1行しか出ず、違反の一覧はテストレポートを開かないと読めません。
   • katachi { architecture = ... }: ドキュメント生成・テンプレートが定義を見つけるための指定です。値は手順3で書く定義の完全修飾名（package + 変数名）にします。

   Android プロジェクトの場合

   ルートの build.gradle.kts に kotlin("jvm") version "..." apply false を書き、モジュール側ではバージョンを書かずに kotlin("jvm") とだけ書いてください。

   Kotlin のバージョン（2.2 以上。2.4 未満ならコンパイラオプションが要る）

   Kotlin は 2.2 以上 を使ってください。それより前の Kotlin は katachi のライブラリの metadata を読めません。

   ktFile() や konsist { } などは context parameters で宣言しています。Kotlin 2.4 未満 では、次のオプションが無いと呼べません（2.4 以降では付けないでください。警告になります）。

   architecture-test/build.gradle.kts

   kotlin {
       compilerOptions.freeCompilerArgs.add("-Xcontext-parameters")
   }

3. アーキテクチャを定義する。

   architecture-test/src/test/kotlin/<パッケージ>/ProjectArchitecture.kt がエントリーポイントです。

   // 例
   @file:OptIn(ExperimentalKatachiApi::class)
   
   package com.example
   
   import me.tbsten.katachi.ExperimentalKatachiApi
   import me.tbsten.katachi.dsl.architecture
   import me.tbsten.katachi.dsl.gradle.gradle
   import me.tbsten.katachi.dsl.kotlin.ktFile
   
   val projectArchitecture = architecture {
       gradle() // wrapper・settings・build スクリプトなど Gradle のファイル
       "domain".group {
           "UseCase" {
               summary = "各画面で発生するアプリ固有の1つの振る舞い"
               layout {
                   "domain/src/main/kotlin/usecase" / "*UseCase".ktFile()
               }
           }
       }
   }

   Show moreShow less

4. 検査する1本のテストを書く

   architecture-test/src/test/kotlin/<パッケージ>/ProjectArchitectureTest.kt

   @file:OptIn(ExperimentalKatachiApi::class)
   
   package com.example
   
   import me.tbsten.katachi.ExperimentalKatachiApi
   import me.tbsten.katachi.check.assert
   import org.junit.jupiter.api.Test
   
   class ProjectArchitectureTest {
       @Test
       fun `プロジェクトの構成が定義どおりになっている`() {
           projectArchitecture.assert()
       }
   }

   プロジェクトが書くテストはこれ1本だけです。 リポジトリ全体の違反が1つの失敗メッセージに集まるので、ルールごとにテストを分ける意味がありません。

   定義に konsist { } を書いたら、assert() の代わりに assert(FileConstraintCheck()) を呼びます。assert() だけでは制約が評価されず、テストが落ちます。詳しくは Konsist との統合 を参照してください。

5. 実行する

   ./gradlew :architecture-test:test

   最初は 宣言していないファイルやディレクトリが違反として出ます。 katachi は許可リスト方式なので、これが正常な出発点です。出てきたパスを定義に足すか、消すかを決めていってください。

   Gradle のファイル（wrapper・settings.gradle.kts・build スクリプト・gradle.properties・version catalog）は、手順3の gradle() の1行で宣言できます。buildSrc や convention plugin がある場合は Gradle 周辺のレシピ を参照してください。

   既存の違反が多くてすぐには片付けられない場合は、実験的な機能の baseline で今ある違反をとりあえず許容し、新しい違反だけをエラーにすることもできます。詳しくは baseline を参照してください。

導入できたことを確かめる

AI Agent に検証させる

AI Agent に実際にタスクを渡し、アーキテクチャルールに違反するファイルを生成しないことを確かめてみましょう。

今後発生しうる実装タスクがある場合

今後実際に発生するタスクがあるなら、それを試しに実行させて、katachi が機能するかを確かめるのが効果的です。 タスクの内容を AI Agent に渡して実行させてください。

JIRA や Notion などで管理しているタスクチケットがあれば、それをそのまま渡すのも手です。

特にない場合

架空のタスクを AI Agent に考えさせて、katachi がガードレールとして機能するか検証させましょう。

このプロジェクトで将来発生しそうな架空のタスクをいくつか考えてください。

手動で検証する

1. アーキテクチャルールに違反するコード例を考え、実際にそのソースファイルを作成してください。
2. ./gradlew :architecture-test:test を実行して、アーキテクチャテストが失敗することを確認してください。

オプション
CI に組み込む

品質を維持するには、katachi のアーキテクチャテストを CI に組み込み、定期的に実行させることが大切です。

Github Actions

以下のようなワークフローファイルを追加してください。

.github/workflows/architecture.ymlShow moreShow less

name: Architecture

on:
  push:
    branches: [main]
  pull_request:

permissions:
  contents: read

jobs:
  architecture:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7

      - uses: actions/setup-java@v6
        with:
          distribution: temurin
          java-version: '17'

      - uses: gradle/actions/setup-gradle@v6

      - run: ./gradlew :architecture-test:test

Show moreShow less

その他の CI システム

次のようなワークフローを、それぞれの CI システムの仕様に合わせて記述します。

1. Java をセットアップする。
2. ./gradlew :architecture-test:test を実行する。
3. 2 の結果をレポートする。

次のステップ

• katachi への理解を深め、architecture 定義を洗練させるには、各種ガイドを参照してください。
  • 基本的な API
  • Role
  • Layout
  • Konsist との統合
  • ドキュメント生成
  • テンプレートからコード生成
  • baseline