·

Tiếng Việt: Setting Up A Production Grade AI Assisted Development Environment

Setting Up A Production Grade AI Assisted Development Environment

Một agent giỏi trong một môi trường thiết lập sơ sài vẫn sẽ tạo ra kết quả tồi — môi trường bạn xây dựng xung quanh agent quan trọng không kém bản thân model bạn chọn.

Vì Sao Thiết Lập Môi Trường Không Phải Việc Làm Một Lần

Nhiều kỹ sư coi việc "cài AI tool" giống như cài một plugin thông thường: cài một lần, dùng mãi mãi. Đây là cách nhìn sai lầm dẫn đến rất nhiều kết quả kém chất lượng từ agent. Môi trường phát triển với AI ở chuẩn production cần được xem như một phần sống của codebase — nó cần được cập nhật khi convention của team thay đổi, khi công cụ mới ra mắt, khi bạn phát hiện agent liên tục mắc cùng một lỗi vì thiếu ngữ cảnh nào đó.

Có ba lý do cụ thể khiến việc này cần được duy trì liên tục thay vì "set and forget":

  1. Codebase thay đổi liên tục. Một quy ước đặt tên mới, một thư viện mới được thêm vào, một cấu trúc thư mục được tái tổ chức — nếu file cấu hình (CLAUDE.md, MCP server) không được cập nhật theo, agent sẽ tiếp tục dựa vào thông tin lỗi thời, tạo ra code không nhất quán với phần còn lại của hệ thống.
  2. Model và công cụ agentic tiến hóa nhanh. Một tính năng mới (ví dụ một loại hook mới, một cách cấu hình MCP mới) có thể cải thiện đáng kể chất lượng output, nhưng chỉ khi bạn chủ động áp dụng nó.
  3. Lỗ hổng bảo mật xuất hiện từ chính việc dùng AI. Một agent với quyền truy cập quá rộng, một API key bị lộ vào lịch sử chat, một MCP server kết nối tới hệ thống nhạy cảm không được giới hạn quyền đúng cách — đây là những rủi ro chỉ xuất hiện sau khi bạn đã tích hợp AI sâu vào quy trình, không có sẵn từ đầu.

Một tổ chức trưởng thành trong agentic engineering thường có một quy trình review định kỳ (hàng tháng hoặc mỗi sprint) cho các file cấu hình AI, y hệt cách họ review lại CI/CD pipeline hay dependency.

Mẹo: Đưa CLAUDE.md và các file cấu hình MCP vào cùng quy trình pull request như code thông thường — mọi thay đổi convention quan trọng của team nên đi kèm một PR cập nhật CLAUDE.md tương ứng, thay vì để nó trôi dần ra khỏi thực tế.

Cài Đặt Và Cấu Hình Claude Code

Claude Code được cài đặt qua npm và chạy như một công cụ dòng lệnh độc lập, có thể tích hợp thêm vào IDE nếu muốn. Các bước cài đặt cơ bản:

npm install -g @anthropic-ai/claude-code
claude --version

Sau khi cài, xác thực tài khoản (qua Claude Console hoặc Claude Pro/Max tùy gói bạn dùng):

claude

Sau bước cài đặt cơ bản, có một số cấu hình nên thiết lập ngay từ đầu để đảm bảo chất lượng production:

  • Cấu hình permission (quyền hạn) — quyết định lệnh nào agent được phép chạy tự động, lệnh nào cần xác nhận thủ công. Đây là bước quan trọng nhất về mặt an toàn, sẽ được đào sâu ở Module 10 (Bảo mật và sử dụng AI có trách nhiệm), nhưng cần thiết lập cơ bản ngay từ ngày đầu — ví dụ luôn yêu cầu xác nhận cho các lệnh git push, thao tác xóa file, hay lệnh migration database.
  • Cấu hình model — chọn model phù hợp cho từng loại tác vụ (một số thiết lập cho phép dùng model nhanh/rẻ hơn cho việc đơn giản, model mạnh hơn cho việc phức tạp).
  • Thiết lập theo từng project riêng biệt — mỗi repo nên có cấu hình Claude Code riêng (thường nằm trong thư mục .claude/ ở root repo) thay vì dùng chung một cấu hình toàn cục cho mọi dự án, vì mỗi codebase có convention và mức độ rủi ro khác nhau.

Một thử nghiệm nên làm ngay sau khi cài đặt xong: mở Claude Code trong một repo thật và thử một yêu cầu đơn giản để xác nhận nó đọc đúng codebase:

Repo này dùng ngôn ngữ/framework gì, và test được chạy bằng lệnh nào?

Nếu câu trả lời sai hoặc mơ hồ, đó là dấu hiệu cho thấy bạn cần đầu tư ngay vào bước tiếp theo: viết CLAUDE.md.

Mẹo: Cài Claude Code trên một repo test/nháp trước khi dùng trên codebase production quan trọng nhất — để bạn quen với cách nó khám phá code và phản ứng ra sao với các loại prompt khác nhau mà không có áp lực rủi ro thật.

Viết CLAUDE.md Thực Sự Hiệu Quả

CLAUDE.md là file cấu hình ở dạng Markdown mà Claude Code tự động đọc khi bắt đầu làm việc trong một repo — đây chính là "bản tóm tắt onboarding" bạn đưa cho agent, tương tự tài liệu bạn đưa cho một kỹ sư mới gia nhập team. Chất lượng của file này ảnh hưởng trực tiếp và mạnh mẽ đến chất lượng mọi tác vụ agent thực hiện sau đó — đây là đòn bẩy cấu hình quan trọng nhất trong toàn bộ môi trường agentic của bạn.

Một CLAUDE.md tốt cần trả lời được các câu hỏi mà một kỹ sư mới thường hỏi trong tuần đầu tiên: dự án này làm gì, dùng công nghệ gì, cấu trúc thư mục ra sao, có quy ước nào bắt buộc phải theo, test chạy thế nào, và các lệnh thường dùng là gì.

Dưới đây là một ví dụ CLAUDE.md cho một dịch vụ thanh toán, minh họa cấu trúc nên có:


## Tech Stack
- Node.js 20, TypeScript (strict mode)
- Express for HTTP layer
- PostgreSQL via Prisma ORM
- Stripe SDK for payment processing
- Vitest for testing

## Repository Layout
- `src/api/` — HTTP route handlers, thin controllers only
- `src/services/` — business logic, no direct DB access here
- `src/repositories/` — all Prisma queries live here, nowhere else
- `src/webhooks/` — Stripe webhook handlers, must be idempotent
- `tests/` — mirrors src/ structure, one test file per module

## Key Conventions
- Never call Prisma directly from `src/api/` or `src/services/` —
  always go through `src/repositories/`.
- All monetary values are stored as integer cents, never floats.
- Every webhook handler must be idempotent — check `event.id` against
  the `processed_events` table before applying side effects.
- Use dependency injection via constructor, not singletons, for all
  service classes.

## Test Requirements
- Every new endpoint requires at least one happy-path test and one
  error-path test.
- Webhook handlers require a test for duplicate event delivery.
- Do not mock Prisma in repository tests — use the test database.

## Commands
- `npm run dev` — start local server with hot reload
- `npm test` — run full test suite
- `npm run test:watch -- <pattern>` — run tests matching pattern
- `npm run db:migrate` — apply pending Prisma migrations
- `npm run lint` — run ESLint + Prettier check

Vài nguyên tắc khi viết CLAUDE.md cho chính dự án của bạn:

  • Ưu tiên điều agent không thể tự suy ra được từ việc đọc code. Đừng lãng phí không gian mô tả những gì agent có thể tự nhìn thấy (ví dụ liệt kê hết tên file) — tập trung vào convention ngầm định, lý do đằng sau quyết định kiến trúc, và các ràng buộc "bắt buộc phải theo" mà không đọc code sẽ không biết.
  • Cụ thể hóa các lỗi thường gặp. Nếu agent (hoặc kỹ sư mới) từng mắc một lỗi cụ thể nhiều lần (ví dụ quên idempotency ở webhook), hãy viết thẳng điều đó vào CLAUDE.md thay vì hy vọng nó tự đoán ra.
  • Giữ file gọn và cập nhật, không để nó phình to thành tài liệu bách khoa. Một CLAUDE.md quá dài, chứa thông tin lỗi thời, còn tệ hơn không có gì — vì nó chiếm context window mà không mang lại giá trị tương xứng.
  • Có thể có nhiều CLAUDE.md lồng nhau. Với monorepo, mỗi package/service con có thể có CLAUDE.md riêng bổ sung cho file gốc ở root, giúp agent chỉ tải đúng ngữ cảnh liên quan đến phần đang làm việc.

Mẹo: Sau mỗi lần agent làm sai điều gì đó vì thiếu ngữ cảnh, đừng chỉ sửa code — hãy tự hỏi "câu này có nên được thêm vào CLAUDE.md không?" Đây là cách CLAUDE.md của bạn trưởng thành dần theo thời gian, giống một cuốn sổ tay đội ngũ liên tục được bổ sung.

Cấu Hình MCP Server Để Tích Hợp Với Dự Án Thực Tế

MCP (Model Context Protocol) là một chuẩn giao thức mở cho phép agent kết nối với các nguồn dữ liệu và công cụ bên ngoài — database, issue tracker, dịch vụ nội bộ, API bên thứ ba — theo một cách chuẩn hóa, thay vì mỗi tích hợp phải viết riêng một tool tùy chỉnh. Với Claude Code, MCP server là cách chính để mở rộng khả năng của agent vượt ra ngoài việc đọc/ghi file và chạy shell command thuần túy.

Một số MCP server phổ biến hữu ích cho môi trường phát triển thực tế:

  • MCP server cho database — cho phép agent tự truy vấn schema thật, thậm chí chạy query kiểm tra (ở chế độ chỉ đọc) để xác minh giả định trước khi viết migration hay code liên quan đến dữ liệu.
  • MCP server cho issue tracker (Jira, Linear, GitHub Issues) — cho phép agent tự đọc chi tiết ticket, cập nhật trạng thái, hoặc tạo sub-task, giảm việc bạn phải copy-paste nội dung ticket vào prompt thủ công.
  • MCP server cho tài liệu nội bộ / wiki — giúp agent tra cứu quy trình, kiến trúc hệ thống được ghi lại ở nơi khác ngoài code, mà không cần bạn dán toàn bộ nội dung vào mỗi lần hỏi.
  • MCP server cho monitoring/observability (log, metrics) — cho phép agent tự tra log lỗi thật từ production khi debug, thay vì chỉ dựa vào mô tả bằng lời của bạn.

Cấu hình MCP server trong Claude Code thường thực hiện qua file cấu hình dự án hoặc lệnh CLI, ví dụ đăng ký một server:

claude mcp add postgres-readonly \
  --command "npx" \
  --args "-y,@modelcontextprotocol/server-postgres,postgresql://readonly_user@localhost/mydb"

Nguyên tắc quan trọng khi cấu hình MCP server cho môi trường production:

  • Luôn dùng tài khoản/credential có quyền hạn tối thiểu (least privilege) — ví dụ MCP server kết nối database nên dùng user chỉ có quyền đọc (read-only) trừ khi có lý do rõ ràng cần quyền ghi, và quyền ghi đó cần được giới hạn phạm vi cụ thể.
  • Không kết nối trực tiếp MCP server vào production nếu có thể tránh — ưu tiên kết nối vào môi trường staging hoặc bản sao dữ liệu đã được ẩn danh hóa (anonymized) cho các tác vụ phát triển thông thường.
  • Xem xét kỹ MCP server của bên thứ ba trước khi cài — vì MCP server chạy như một process riêng có thể truy cập dữ liệu nhạy cảm, hãy áp dụng mức độ thẩm định (vetting) tương đương như khi thêm một dependency mới vào production, không cài đại từ nguồn không rõ ràng.

Mẹo: Bắt đầu với một MCP server duy nhất (ví dụ database read-only) và quan sát cách agent sử dụng nó trong một tuần trước khi thêm nhiều server cùng lúc — quá nhiều tool khả dụng ngay từ đầu có thể khiến agent chọn sai tool hoặc tốn context không cần thiết để quyết định.

Quản Lý API Key Và Secret An Toàn

Khi tích hợp AI sâu vào quy trình phát triển, số lượng secret bạn cần quản lý tăng lên đáng kể: API key của nhà cung cấp model, credential cho từng MCP server, token truy cập issue tracker... Nguyên tắc nền tảng không thay đổi so với quản lý secret truyền thống, nhưng có thêm rủi ro riêng: agent có thể vô tình đọc và đưa secret vào context, hoặc tệ hơn, in secret ra log/output mà bạn không để ý.

Quy tắc cơ bản cần tuân thủ:

  • Không bao giờ commit secret vào git, dù là file .env hay hardcode trực tiếp trong code.
  • Luôn liệt kê các file chứa secret trong .gitignore ngay từ commit đầu tiên của dự án, không đợi đến khi có secret thật mới thêm vào.
  • Không dán secret trực tiếp vào prompt khi trò chuyện với agent — nếu cần agent biết một giá trị nhạy cảm để debug, hãy dùng biến môi trường và để agent tự đọc qua tool (với quyền hạn giới hạn), thay vì gõ giá trị thật vào chat.
  • Định kỳ xoay vòng (rotate) API key, đặc biệt các key được dùng bởi MCP server hoặc agent có quyền truy cập rộng.

Ví dụ cấu trúc file .env (không bao giờ commit):

ANTHROPIC_API_KEY=sk-ant-xxxxxxxxxxxxxxxx
DATABASE_URL=postgresql://user:password@localhost:5432/mydb
STRIPE_SECRET_KEY=sk_test_xxxxxxxxxxxxxxxx
JIRA_API_TOKEN=xxxxxxxxxxxxxxxx

Và .gitignore tương ứng phải đảm bảo mọi biến thể của file env đều được loại trừ:

.env
.env.local
.env.*.local
*.pem
.claude/settings.local.json

Lưu ý riêng với môi trường agentic: file cấu hình cục bộ của Claude Code (thường có hậu tố .local) cũng có thể chứa thông tin nhạy cảm (đường dẫn nội bộ, token cấu hình MCP) — nên được liệt kê trong .gitignore giống như bất kỳ file secret nào khác, trong khi file cấu hình chung không chứa secret (như CLAUDE.md, cấu hình MCP không kèm credential) vẫn nên được commit để cả team dùng chung.

Mẹo: Chạy một lần quét secret (secret scanning) trên toàn bộ lịch sử git của repo trước khi bắt đầu dùng agent sâu vào codebase — nếu có secret cũ từng bị commit nhầm trong quá khứ, agent có thể vô tình đọc thấy chúng khi khám phá code, dù bạn đã xóa ở commit sau.

Cấu Hình Git Hook Cho Commit Message Có Sự Hỗ Trợ Của AI

Một cách tận dụng AI thiết thực nhưng ít được chú ý là tự động hóa việc viết commit message chất lượng — thông qua Git hook chạy tại thời điểm commit. Đây là ví dụ ứng dụng nhỏ nhưng minh họa rõ nguyên tắc lớn hơn: AI có thể được nhúng vào bất kỳ điểm nào trong quy trình phát triển, không chỉ ở bước viết code.

Cách tiếp cận phổ biến là dùng Husky (công cụ quản lý Git hook cho dự án Node.js) kết hợp một script gọi AI để phân tích diff đang được commit và gợi ý một commit message theo đúng convention của team (ví dụ Conventional Commits).

Ví dụ một hook prepare-commit-msg sử dụng Husky:

#!/usr/bin/env sh

COMMIT_MSG_FILE=$1
COMMIT_SOURCE=$2

if [ -z "$COMMIT_SOURCE" ]; then
  DIFF=$(git diff --cached)
  if [ -n "$DIFF" ]; then
    SUGGESTION=$(echo "$DIFF" | ai-commit-helper --format conventional-commits)
    echo "$SUGGESTION" > "$COMMIT_MSG_FILE"
  fi
fi

Trong đó ai-commit-helper là một script nhỏ (có thể tự viết bằng cách gọi API của Claude, hoặc dùng tính năng có sẵn nếu công cụ agentic của bạn hỗ trợ) nhận diff đang staged qua stdin và trả về một commit message theo định dạng đã định (ví dụ feat:, fix:, refactor: theo Conventional Commits).

Nguyên tắc quan trọng khi áp dụng AI vào Git hook:

  • Luôn cho phép con người chỉnh sửa message được gợi ý trước khi commit hoàn tất — không nên tự động hoàn toàn không qua xác nhận, vì AI có thể hiểu sai ý định đằng sau một diff phức tạp.
  • Giữ hook đủ nhanh — nếu gọi API bên ngoài làm chậm quá trình commit đáng kể, kỹ sư sẽ có xu hướng bỏ qua hook (dùng --no-verify), làm mất giá trị của toàn bộ thiết lập.
  • Không để hook phụ thuộc vào việc luôn có mạng/API khả dụng — nên có cơ chế fallback (ví dụ giữ nguyên message thủ công nếu gọi AI thất bại) để không chặn hoàn toàn quy trình commit khi có sự cố.

Mẹo: Thử nghiệm hook này trên một nhánh cá nhân trong 1-2 tuần trước khi áp dụng bắt buộc cho cả team — commit message là thứ chạm vào mọi kỹ sư mỗi ngày, nên một hook gây khó chịu (chậm, gợi ý sai) sẽ nhanh chóng bị cả team phản đối nếu chưa được tinh chỉnh kỹ.

Thực Hành: Thiết Lập Môi Trường Hoàn Chỉnh Từ Đầu Đến Cuối

Bài tập này yêu cầu bạn dựng toàn bộ môi trường agentic production-grade cho một repo thật (hoặc repo mẫu nếu chưa sẵn sàng áp dụng lên dự án chính).

Bước 1 — Cài đặt Claude Code theo hướng dẫn ở phần trên, xác nhận đăng nhập thành công, và chạy thử một câu hỏi đơn giản để kiểm tra nó truy cập đúng repo.

Bước 2 — Viết CLAUDE.md đầu tiên cho dự án của bạn. Dùng chính agent để giúp bạn khởi tạo bản nháp, sau đó tự tay review và bổ sung phần convention/lỗi thường gặp mà chỉ con người mới biết:

Hãy đọc qua cấu trúc repo này và đề xuất một bản nháp CLAUDE.md theo
mẫu: Tech Stack, Repository Layout, Key Conventions, Test Requirements,
Commands. Đừng bịa ra quy ước — chỉ liệt kê những gì bạn quan sát
được thực sự từ code, và đánh dấu rõ phần nào bạn không chắc chắn
để tôi tự điền.

Bước 3 — Thiết lập ít nhất một MCP server phù hợp với dự án (database read-only là lựa chọn an toàn để bắt đầu), xác nhận credential dùng đúng nguyên tắc quyền hạn tối thiểu.

Bước 4 — Rà soát .gitignore và quy trình quản lý secret. Kiểm tra mọi file .env* đã được loại trừ, chạy một lần quét secret trên lịch sử git nếu đây là repo đã có sẵn từ trước.

Bước 5 — (Tùy chọn) Thiết lập Git hook hỗ trợ commit message nếu team bạn muốn chuẩn hóa commit message, thử nghiệm trên nhánh cá nhân trước.

Bước 6 — Kiểm tra toàn bộ bằng một tác vụ thật. Giao một task thực tế cho agent và quan sát: nó có tự động áp dụng đúng convention từ CLAUDE.md không? Nó có dùng đúng MCP server khi cần thông tin từ database không? Không có secret nào bị lộ ra trong quá trình làm việc?

Mẹo: Lưu lại toàn bộ thiết lập này (CLAUDE.md, cấu hình MCP không chứa credential, Git hook) trong chính repo và commit lại — đây là tài sản chung của team, không phải cấu hình cá nhân, và nó nên tiến hóa theo cùng quy trình review như mọi thay đổi code khác.

Những điểm chính

  • Môi trường phát triển với AI cần được bảo trì liên tục như một phần sống của codebase, không phải thiết lập một lần rồi bỏ quên.
  • CLAUDE.md là đòn bẩy cấu hình quan trọng nhất — nên tập trung vào điều agent không tự suy ra được từ code (convention ngầm định, lỗi thường gặp, ràng buộc bắt buộc), giữ gọn và luôn cập nhật.
  • MCP server mở rộng khả năng agent ra ngoài file/shell, nhưng cần áp dụng nguyên tắc quyền hạn tối thiểu và thẩm định kỹ trước khi kết nối vào hệ thống nhạy cảm.
  • Quản lý secret trong môi trường agentic có rủi ro riêng — agent có thể vô tình đọc hoặc để lộ secret — nên cần .gitignore đầy đủ, không dán secret vào prompt, và quét secret định kỳ.
  • Git hook có AI hỗ trợ (như gợi ý commit message) là ví dụ cho nguyên tắc rộng hơn: AI có thể nhúng vào bất kỳ điểm nào trong quy trình, miễn là luôn giữ khả năng con người kiểm soát và có cơ chế fallback khi AI không khả dụng.