Bắt đầu dự án mới với CLI như Claude Code: hướng dẫn từng bước

Contents

Dựng một dự án mới thì ai cũng làm được. Nhưng nếu bạn định làm việc với một AI agent chạy trên CLI — Claude Code hay tương tự — thì thứ tự các bước quan trọng hơn bạn tưởng. Agent chỉ giỏi khi ngữ cảnh rõ; và ngữ cảnh rõ nhất là ngữ cảnh bạn ghi ra file ngay từ đầu, chứ không phải nhắc lại trong mỗi lượt chat.

Bài này là quy trình tôi dùng cho mỗi repo mới. Mục tiêu: đến commit đầu tiên, agent đã có đủ thứ để tự định hướng.

1. Chuẩn bị môi trường

mkdir ~/projects/my-app && cd ~/projects/my-app
git init

Trước khi viết dòng code nào, tạo ba file nền:

.gitignore — theo ngôn ngữ. Đừng để agent (hoặc bạn) lỡ tay commit node_modules/, .env, hay build artifact.
README.md — mô tả ngắn: dự án làm gì, chạy thế nào. Một đoạn cũng được, miễn là thật.
.env.example — nếu có secrets. Liệt kê tên biến, không giá trị. File này commit được; .env thật thì không.

2. Khởi tạo context cho AI agent

Đây là bước phân biệt “gõ lệnh với AI” và “làm việc với agent”. Tạo CLAUDE.md ở root — đây là file agent đọc đầu tiên mỗi phiên.

# <Tên dự án>

## Mục tiêu
<1–2 câu>

## Stack
- Language: ...
- Framework: ...
- Database: ...

## Cấu trúc
- src/       code chính
- tests/     unit tests
- docs/      tài liệu

## Lệnh thường dùng
- dev:    <lệnh>
- test:   <lệnh>
- build:  <lệnh>

Giữ nó ngắn và có ý kiến. CLAUDE.md không phải chỗ chép tài liệu — nó là chỗ ghi những gì agent không tự suy ra được từ code: quyết định kiến trúc, quy ước đặt tên, ranh giới không được vượt. Context dài để trong docs/.

Tạo folder docs/ chứa các tài liệu sống, cập nhật dần:

project-overview-pdr.md — Product Design Requirements: dự án giải quyết vấn đề gì, cho ai.
system-architecture.md — kiến trúc, luồng dữ liệu, các thành phần chính.
code-standards.md — quy chuẩn code, quy ước commit.
project-roadmap.md — lộ trình, phase, milestone.

Chưa có gì để viết cũng cứ tạo file rỗng với vài dòng khung. Agent sẽ điền dần khi bạn yêu cầu, và lần sau nó biết chỗ để đọc.

3. Chọn & scaffold stack

Để agent scaffold cũng được, nhưng bạn nên biết lệnh gốc để kiểm chứng:

Loại	Lệnh scaffold
Next.js	`bunx create-next-app@latest .`
Vite + React	`bun create vite . --template react-ts`
Node API	`bun init`
Python	`uv init` hoặc `poetry init`
Go	`go mod init <module>`

Scaffold vào thư mục hiện tại (dấu . cuối lệnh) để không lồng thêm một cấp thư mục thừa. Sau khi scaffold xong, cập nhật ngay phần Stack và Lệnh thường dùng trong CLAUDE.md cho khớp thực tế — đây là chỗ dễ để lệch nhất.

4. Cấu hình chất lượng code

Dựng hàng rào chất lượng trước khi có nhiều code, không phải sau:

Linter/formatter — eslint + prettier, ruff, gofmt, biome…
Pre-commit hook — husky / lefthook / pre-commit. Chặn lỗi ngay ở máy, không đẩy sang CI.
Type-check — tsc --noEmit, mypy, pyright.
Test runner — vitest, jest, pytest, go test.

Ghi đúng các lệnh này vào CLAUDE.md mục “Lệnh thường dùng”. Khi agent kết thúc một thay đổi, nó biết phải chạy gì để tự kiểm chứng — thay vì bạn phải nhắc mỗi lần.

5. CI tối thiểu

Một file .github/workflows/ci.yml với ba job chạy trên mỗi PR là đủ để bắt đầu:

lint  →  typecheck  →  test

Chưa cần deploy, chưa cần matrix nhiều phiên bản. Ba job này bắt phần lớn hồi quy, và cho bạn (cùng agent) một tín hiệu xanh/đỏ rõ ràng trước khi merge.

6. Commit ban đầu

git add -A
git commit -m "feat: initial project scaffold"
git branch -M main
git remote add origin <url>
git push -u origin main

Commit này chốt lại toàn bộ khung: .gitignore, README.md, CLAUDE.md, docs/, scaffold, hàng rào chất lượng, CI. Từ đây agent làm việc trên một nền đã có ngữ cảnh.

7. Vòng làm việc hằng ngày với agent

git checkout -b feat/<slug> — mỗi việc một nhánh.
Mô tả yêu cầu → agent đọc CLAUDE.md + docs/ để bám ngữ cảnh, không cần bạn dán lại.
Implement → verify (chạy dev server / test). Đừng tin “đã xong” khi chưa thấy test xanh.
Commit theo conventional commits: feat:, fix:, refactor:.
PR → CI xanh → merge.

Mấu chốt là bước 3. Agent viết code nhanh; giá trị của bạn nằm ở chỗ đóng vòng kiểm chứng — chạy thật, đọc lỗi thật, không để nó dừng ở “trông có vẻ đúng”.

8. Cập nhật tài liệu liên tục

Sau mỗi feature lớn, cập nhật lại các tài liệu trong docs/ cho khớp với thực tế code: codebase-summary.md, system-architecture.md, project-roadmap.md.

Đây không phải việc làm cho đẹp. Tài liệu lệch còn tệ hơn không có: nó khiến agent bám vào một ngữ cảnh sai và tự tin làm sai. Coi docs/ và CLAUDE.md như một phần của code — chúng lệch thì cả người lẫn agent đều đi lạc.

Tóm lại

Thứ tự đáng nhớ: git → file nền → CLAUDE.md → scaffold → hàng rào chất lượng → CI → commit đầu. Bốn bước đầu là thứ khiến một agent CLI làm việc như một cộng sự có ngữ cảnh, chứ không phải một cỗ máy đoán mò. Phần còn lại chỉ là giữ cho ngữ cảnh đó không lệch theo thời gian.