還記得第一次讓 Claude 幫我寫 Kotlin 程式碼時的對話：

我：幫我加個新功能到專案裡
Claude：好的，請問是什麼專案？使用什麼技術棧？
我：Kotlin 專案
Claude：是 Android 還是後端？用什麼框架？
我：KMP，用 Compose
Claude：資料庫用什麼？架構是怎樣的？
我：SQLDelight，Clean Architecture...
（對話持續了 10 分鐘還在釐清背景）

每次對話都要重新解釋一遍專案背景，效率低到讓人崩潰。

這時我想到：如果 AI 助手一開始就知道所有專案規範，那該有多好？

CLAUDE.md 的誕生：專案說明書

CLAUDE.md 是一個特殊的文件，專門為 AI 助手（特別是 Claude）設計，讓它在進入專案時就能立即理解專案架構、開發規範、常用指令、檔案結構和注意事項。

用什麼技術、什麼模式。程式碼風格、命名規則。如何建置、測試、部署。程式碼放哪裡、文件在哪裡。容易踩的坑、特殊約定。

像在培訓新同事

我把撰寫 CLAUDE.md 想像成在培訓一個新加入的開發者。

這個開發者技術能力很強，就是 AI 的能力。但不了解專案背景，需要我們提供。學習速度很快，讀取文件只需幾秒。需要明確指引，要有清楚的規範。

CLAUDE.md 的核心結構

讓我們來看看 Grimo 專案的 CLAUDE.md 是如何組織的：

1. 開場白：設定基調

# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) 
when working with code in this repository.

始終用繁體中文說明

依照 馬斯克 第一性原理

設計要點：

• 明確說明文件用途
• 設定語言偏好（繁體中文）
• 建立開發哲學（第一性原理）

2. 專案概覽：快速理解

## Project Overview

**Grimo** is a Kotlin Multiplatform (KMP) desktop AI assistant 
application. Currently targeting macOS with 
architecture ready for Android/iOS expansion.

An AI-powered task management and orchestration platform 
designed to coordinate AI CLI tools...

設計要點：

• 一段話說清楚專案是什麼
• 點出關鍵技術選型
• 說明目標平台和未來規劃

3. 技術棧：具體版本很重要

## Technology Stack

- **Kotlin 2.2.0** with **Compose Multiplatform 1.8.2** for UI
- **SQLDelight 2.1.0** for type-safe database access
- **Ktor 3.2.1** for HTTP networking
- **Koin 4.1.0** for dependency injection
- **Gradle 8.14.2** build system with version catalog

設計要點：

• 列出具體版本號（避免 API 不相容）
• 簡短說明每個技術的用途
• 使用粗體突出重要資訊

4. 架構說明：視覺化很重要

## Architecture

The project follows **Clean Architecture** with **MVI** pattern:

shared/src/commonMain/kotlin/dev/grimo/
├── domain/
│   ├── model/         # Business entities
│   └── repository/    # Repository interfaces
├── core/              # Cross-platform utilities
└── di/                # Dependency injection setup

設計要點：

• 用樹狀圖展示目錄結構
• 每個目錄加上簡短註解
• 強調架構模式（Clean + MVI）

5. 必要指令：可複製貼上最重要

## Essential Commands

### Build & Run
- `./gradlew clean build --no-daemon` - Clean and rebuild
- `./gradlew :desktopApp:run` - Run the desktop application
- `./gradlew :desktopApp:run -Dauberst.debug=true` - Debug mode

### Code Formatting
- `./gradlew ktfmtFormat` - Format all Kotlin source files
- `./gradlew ktfmtCheck` - Check if formatting is needed

設計要點：

• 指令要完整可執行
• 分類組織（建置、測試、格式化）
• 加上簡短說明

6. 開發流程：Step by Step

## Code Organization

When implementing features:

1. **Domain Layer** (`shared/src/commonMain/kotlin/.../domain/`):
   - Define entities in `model/`
   - Create repository interfaces in `repository/`

2. **Data Layer** (`shared/src/desktopMain/kotlin/.../data/`):
   - Implement repositories
   - Add SQLDelight queries in `.sq` files

3. **Presentation Layer** (`desktopApp/src/jvmMain/kotlin/.../presentation/`):
   - Create ViewModels with MVI state management
   - Compose UI components

設計要點：

• 明確的步驟順序
• 具體的檔案位置
• 說明每層的職責

7. 重要文件連結：知識地圖

## Important Documentation

**CRITICAL**: Always read relevant documentation before 
implementing features and update documentation after making changes.

### Documentation Structure
- `docs/README.md` - Project overview and navigation
- `docs/tasks/README.md` - **MUST READ** for task-related work
- `docs/design/developer-guide.md` - **MUST READ** before development

設計要點：

• 用 CRITICAL、MUST READ 強調重要性
• 提供文件的簡短說明
• 建立文件閱讀優先級

8. 陷阱警告：避免踩坑

## Important Notes

- Always use SQLDelight's type-safe queries instead of raw SQL
- Keep business logic in the `shared` module
- Platform-specific code only in respective source sets
- Follow MVI pattern for state management

設計要點：

• 列出容易犯的錯誤
• 強調重要原則
• 簡潔明瞭

進階技巧：讓 AI 更聰明

1. 加入程式碼範例

### Creating Loggers

\```kotlin
import io.github.aperionai.auberst.core.logging.createLogger

class MyClass {
    private val logger = createLogger<MyClass>()
    
    fun doSomething() {
        logger.info { "Starting operation" }
        logger.debug { "Operation details: $details" }
    }
}
\```

效果：AI 會模仿你的程式碼風格

2. 定義 AI 的行為準則

## Code Development Principles

### Version and API Management
- **ALWAYS check package versions** before writing code
- **NEVER use deprecated methods or APIs**

### Traditional Chinese Comments
- Add Traditional Chinese comments in places that are difficult to understand
- Focus on explaining "why" rather than "what"

效果：AI 會遵循這些原則

3. 提供決策樹

## Database Migration Best Practices (2025)

The project uses **SQLDelight 2.0+** with:
- **deriveSchemaFromMigrations = true**: Schema from migration files
- **generateAsync = true**: Supports Kotlin Coroutines
- **verifyMigrations = true**: Compile-time validation

### Implementation
- Use `.sqm` files for migrations
- Don't put CREATE TABLE in .sq files when using deriveSchemaFromMigrations

效果：AI 能做出正確的技術決策

實戰效果

沒有 CLAUDE.md 的時候：

我：幫我新增一個 Repository
Claude：我需要了解一些資訊...
（10 分鐘的問答）
Claude：好的，我會創建一個 Repository
（產生的程式碼風格不一致）

有了 CLAUDE.md 之後：

我：幫我新增 ProjectRepository
Claude：根據 CLAUDE.md，我會按照 Clean Architecture 模式：
1. 在 domain/repository/ 創建介面
2. 在 data/repository/ 實作
3. 使用 SQLDelight 查詢
4. 在 Koin module 註冊
（直接產生符合規範的程式碼）

時間大幅縮短。

維護 CLAUDE.md 的最佳實踐

1. 持續更新

# 每次重大變更後更新
git diff CLAUDE.md  # 檢查是否需要更新

2. 版本同步

// 升級套件時同步更新 CLAUDE.md
// libs.versions.toml
[versions]
kotlin = "2.2.0"  // ← 更新這裡
compose = "1.8.2" // ← 也要更新 CLAUDE.md

3. 團隊約定

## Team Conventions (update when changed)
- PR must pass all tests
- Commit message format: type(scope): description
- Code review required for main branch

4. 定期審視

每月檢查：

• [ ] 版本號是否最新
• [ ] 指令是否還能用
• [ ] 新增的約定是否記錄
• [ ] 踩過的坑是否警告

意外收穫：不只是給 AI 看

CLAUDE.md 帶來的額外好處：

1. 新人 Onboarding

新開發者加入時，CLAUDE.md 就是最好的入門文件

2. 自我提醒

三個月後的你會感謝現在寫了 CLAUDE.md

3. 知識沉澱

專案的核心知識都濃縮在這個文件裡

4. 標準化檢查

可以用來檢查程式碼是否符合規範

CLAUDE.md 的 10 個撰寫原則

1. 具體勝於抽象：版本號、路徑、指令要具體
2. 範例勝於說明：show, don't tell
3. 結構化組織：用標題和列表組織資訊
4. 視覺化呈現：用圖表和程式碼區塊
5. 強調重要性：用 CRITICAL、MUST、NEVER 等詞
6. 保持更新：過時的資訊比沒有資訊更糟
7. 簡潔明瞭：AI 讀得快但人也要能讀
8. 可執行性：指令和範例要能直接使用
9. 漸進式披露：從概覽到細節
10. 雙向受益：既幫助 AI 也幫助人類

CLAUDE.md 是專案的使用說明書

CLAUDE.md 就像是專案的使用說明書。

不同的是，傳統文件是寫給人看的，CLAUDE.md 是寫給 AI 看的。但最終目的都是提高開發效率。

對一人公司來說，一個好的 CLAUDE.md 可以讓 AI 助手從「需要指導的實習生」變成「了解專案的資深同事」。

投資在 CLAUDE.md 上的每一分鐘，都會在未來節省你幾小時。

今日金句

「好的規範讓 AI 從工具變成夥伴。」

關於作者：Sam，一人公司創辦人。正在打造 Grimo，一個智能任務管理和分配平台。

專案連結：GitHub - grimostudio