VNPT

The CLAUDE.md (Stage 3: Build)

Đóng gói bối cảnh dự án, commands và conventions cốt lõi vào file root cho Agent đọc tại đầu mỗi session

Bài gốc: Anthropic Claude Academy reference/ai-native-sdlc/course/05-claude-md.md 2026-09-16 ~5 phút đọc

1. Bắt đầu: Vai trò của CLAUDE.md

Trong SDLC truyền thống, context dự án phân mảnh: nằm trên wiki, Confluence lỗi thời hoặc trong đầu kỹ sư thâm niên. Kỹ sư mới mất nhiều tuần để nắm các lệnh build, test, lint và conventions codebase.

Trong AI-Native SDLC, CLAUDE.md đóng gói toàn bộ context kỹ sư mới cần vào ngày đầu tiên: conventions, commands, architecture và lỗi phổ biến. File đặt tại repo root, Agent tự động đọc ở đầu mỗi session, toàn bộ team cùng bảo trì và cập nhật qua PR review mỗi khi phát sinh lỗi.

AI-Native: Root CLAUDE.md

Context nạp tự động vào Context Window ở đầu session: Commands (build, test, lint), Conventions, Architecture, Things Claude gets wrong. Cập nhật qua Git PR review.

Truyền thống: Wiki & Truyền miệng

Tài liệu rời rạc, nhanh lỗi thời; kỹ sư mới mất tuần on-boarding; agent không có context chuẩn dẫn đến chạy sai lệnh hoặc vi phạm conventions.

2. Sơ đồ Context Ingestion & Rule of Two

Sơ đồ kiến trúc Context Ingestion từ repo root vào Context Window ở đầu session, kèm chu trình cập nhật Rule of Two khi phát hiện lỗi lặp lại:

Archify Interactive Architecture: CLAUDE.md Context Ingestion Mở toàn màn hình ↗

3. Các bước thực thi

Quy trình 5 bước thiết lập và duy trì CLAUDE.md tại repository root:

Khởi tạo với /init

Chạy command /init trong repo. Claude quét repo và sinh CLAUDE.md khởi đầu từ các file cấu hình tìm thấy.

command: /init init template

Cắt gọn xuống chuẩn Day One

Kỹ sư rà soát và cắt bỏ nội dung thừa. Chỉ giữ: build, test, lint commands, conventions cốt lõi và các lỗi Claude hay gặp.

Day One context < 1 page

Commit vào Git tại repo root

Lưu file tại CLAUDE.md ở repo root. Toàn team dùng chung một version và mọi thay đổi được review như code qua PR.

git root team shared

Áp dụng Rule of Two

Khi Claude lặp lại cùng một lỗi 2 lần, đưa ngay rule sửa lỗi vào mục Things Claude gets wrong trong CLAUDE.md.

Rule of Two institutional knowledge

Giữ budget dưới 1 trang (< 1 page)

Claude đọc toàn bộ file ở đầu mỗi session; nội dung cũ hoặc thừa làm chiếm Context Window vô ích. Quy trình chuyên sâu theo domain cần tách thành SKILL.md.

budget < 1 page context hygiene

Lean CLAUDE.md (< 1 trang)

Chỉ chứa build/test/lint commands, core conventions, architecture tóm tắt và lỗi Claude hay gặp. Tiết kiệm Context Window cho suy luận code.

Bloated Context (> 3 trang)

Nhồi nhét tài liệu API, hướng dẫn cài đặt môi trường chung, giải thích lý thuyết. Làm loãng Context Window, tăng độ trễ và tăng rủi ro hallucination.

4. Cấu trúc mẫu CLAUDE.md

File CLAUDE.md mẫu cho Payments service tại repo root:

# Payments service
## Commands
- Build: make build
- Test: make test (unit), make itest (integration, needs docker)
- Lint: make lint (runs in CI; fix before pushing)
## Conventions
- Java 21, Spring Boot 3. No new Lombok.
- Money is always BigDecimal, never double.
- Every endpoint needs an integration test in src/itest.
## Architecture
- api/ holds REST controllers, core/ holds domain logic,
  adapters/ talks to external systems.
- Kafka events are defined in schemas/; never edit generated classes.
## Things Claude gets wrong
- Do not bump dependency versions; the platform team owns them.
- The legacy v1/ package is frozen; changes go in v2/.

5. Ranh giới giữa CLAUDE.md và Skills

Đặc tính	CLAUDE.md	SKILL.md
Phạm vi (Scope)	Global context cho toàn repo; áp dụng cho mọi task.	Domain context chuyên biệt; chỉ nạp theo nhu cầu tác vụ.
Thời điểm nạp (Ingestion)	Tự động nạp 100% ở đầu mỗi session làm việc.	Auto-trigger dựa trên semantic matching từ frontmatter description.
Nội dung	Commands (build, test, lint), core conventions, architecture, lỗi hay gặp.	Quy trình chuyên sâu (review bảo mật API, migration database, tối ưu query).
Kích thước (Budget)	Dưới 1 trang (< 1 page); cắt bỏ nội dung cũ định kỳ.	Thư mục Skill gồm `SKILL.md`, scripts kiểm tra và tài liệu references.

6. Kiểm soát & Đo lường

CLAUDE.md lưu trong Git version control: chỉ thị cho Agent minh bạch, kiểm toán được (auditable). Team conventions áp dụng qua file, Git commit history lưu vết thay đổi, code owners phê duyệt qua PR review.

Loại chỉ số	Tên chỉ số	Định nghĩa & Nguồn dữ liệu	Mục tiêu kỹ thuật
Leading Indicator	Mistake Repeat Rate (Tỷ lệ lặp lại lỗi)	Tần suất Claude lặp lại lỗi đáng lẽ `CLAUDE.md` phải bắt. Các chỉnh sửa hoặc thay đổi đối với `CLAUDE.md` được theo dõi trong Git history.	Giảm dần về 0 khi rules phòng ngừa được cập nhật chuẩn xác.
Lagging Indicator	Time to First Merged PR (Thời gian đến PR đầu)	Thời gian đến PR đầu tiên được merge của kỹ sư mới (trích xuất từ PR history).	Rút ngắn xuống < 48 giờ nhờ context chuẩn và tự động hóa.