LumiBaseDocs

Claude Code — LumiBase Agent Setup

Claude Code là một coding agent chạy trên terminal do Anthropic tạo ra. Nó hiểu codebase của bạn, chạy lệnh, chỉnh sửa file, và quản lý git.

Tags: Terminal · Standalone · Cloud · Extension


Thiết lập nhanh (khuyến nghị)

Chạy bên trong Claude Code để nạp toàn bộ ngữ cảnh LumiBase trong một bước:

code
Read docs/en/agent-setup/prompt.md and follow all setup instructions.

Hoặc nếu bạn đang dùng bản copy docs từ xa:

code
Fetch https://raw.githubusercontent.com/khuepm/lumibase/main/docs/en/agent-setup/prompt.md

Thiết lập thủ công

Bước 1 — Mở dự án của bạn

bash
cd /path/to/lumibase
claude

Bước 2 — Nạp ngữ cảnh dự án

Dán nội dung sau vào Claude Code:

code
Read docs/en/README.md to understand the LumiBase monorepo structure.
Then read docs/en/data-model.md for the database schema.
Then read docs/en/ai-skills.md for the skill system conventions.

Bước 3 — Thêm luật LumiBase vào CLAUDE.md

Tạo hoặc thêm vào CLAUDE.md ở thư mục gốc dự án:

markdown
## LumiBase development rules

- Use NanoID or UUIDv7 for all IDs — never auto-increment serial
- Every domain table must have `site_id` for multi-tenancy
- Business logic goes through `@lumibase/runtime` abstractions (not direct CF bindings)
- Prefer 1-roundtrip aggregated API responses
- Dangerous AI actions (schema:write, delete*) must create ai_approvals rows
- Cache invalidation must use tag-based approach (not key enumeration)
- Follow the stack: Hono.js + Drizzle ORM + PostgreSQL + Cloudflare Workers / Docker

Bước 4 — Thiết lập MCP server (tùy chọn)

Nếu bạn muốn Claude Code có quyền truy cập trực tiếp (live) vào LumiBase API:

Thêm vào cấu hình Claude MCP của bạn (~/.claude.json hoặc .claude/mcp.json):

json
{
  "mcpServers": {
    "lumibase": {
      "url": "http://localhost:1989/mcp",
      "env": {
        "LUMIBASE_TOKEN": "<your-access-token>",
        "LUMIBASE_SITE_ID": "<your-site-id>"
      }
    }
  }
}

Sau đó khởi động lại Claude Code và xác minh bằng: /mcp


Các file chính cho Claude Code

Khi bắt đầu một task mới, hãy trỏ Claude Code tới các docs liên quan:

TaskFile cần đọc
Thêm collection / field mớidocs/en/data-model.md + docs/en/features/collections-builder.md
Xây dựng một Flow / automationdocs/en/features/flows-automation.md
Làm việc trên AI Copilotdocs/en/features/ai-copilot.md + packages/ai-skills/src/skills.ts
Thêm một API routedocs/en/api/hono-api-spec.md + apps/cms/src/routes/
Thêm logic permissionsdocs/en/features/permissions-rbac.md
Deploy lên Cloudflaredocs/en/deployment/cloudflare.md
Chạy cục bộdocs/en/deployment/local-development.md

Ví dụ prompt

code
Read docs/en/features/flows-automation.md, then add a new "send-slack" operation type
to the operations engine. Follow the existing pattern for operation handlers.
code
Read docs/en/features/ai-copilot.md. Add a new AI skill called "publishCollection"
that sets a collection's status to "published". Mark it as safe (no HITL needed).
code
Read docs/en/data-model.md. Create a Drizzle migration to add a `tags` text[] column
to the items table, following the site_id multi-tenancy pattern.

Xử lý sự cố

Claude không tìm thấy docs: Đảm bảo bạn đang chạy claude từ thư mục gốc dự án, hoặc cung cấp đường dẫn tuyệt đối.

Lỗi type sau khi thay đổi schema: Chạy pnpm db:generate để regenerate các type Drizzle.

CMS API không khởi động được: Kiểm tra apps/cms/.dev.vars và đảm bảo mọi env var bắt buộc đã được đặt (xem docs/en/deployment/environment-variables.md).


← Quay lại Thiết lập Agent

Last modified: 26/09/2026