CLAUDE.md · git:20260831.3fd0190 · 2026-08-31 · sha256 d40280dea458d393

CLAUDE.md git:20260831.3fd0190A

Immutable. This exact content is served forever at /api/v1/blob/d40280dea458d393.

# CLAUDE.md — Bộ nhớ dự án và kiến trúc

# Version: 1.1.0
# Project: Template khởi đầu SDD + ADD (Starter Template)

---

## 1. Mục đích

Repository là Starter Template theo **SDD** (Spec-Driven Development) và **ADD** (Agent-Driven Development). Dùng template để khởi tạo dự án mới với governance, slash command và tài liệu đặc tả chuẩn hóa.

---

## 2. Kiến trúc và cấu trúc thư mục

### 2.1 Kiến trúc chuẩn

Trạng thái Human Final Review được ghi bằng `/sdd-review`; protocol canonical nằm tại `.claude/skills/_shared/ai-review-protocol.md`.

**Nguồn sự thật kiến trúc:** `.sdd/architecture-profile.md` là profile machine-readable canonical mà SDD/ADD skills sử dụng. `CLAUDE.md` là bộ nhớ kiến trúc dành cho con người và phải phản ánh các thay đổi profile đã approved. Thứ tự chọn: profile approved → repository evidence rõ ràng → input explicit của skill → core-only baseline. Skill không được tự suy đoán HTTP framework, database, ORM/query layer, validation library hoặc test/build command chưa được chọn.

Dự án tuân thủ **Clean Architecture / Hexagonal Architecture**:

```text
src/
├── domain/ # Entity, Value Object, Domain Event thuần TypeScript
├── usecase/ # Luồng ứng dụng, business logic và port
├── interface/ # HTTP/event adapter, DTO và presenter
├── infra/ # Repository, cache và external-service adapter
└── shared/ # Error, logger, bảo mật và tiện ích dùng chung
```

### 2.2 Cấu trúc chuẩn

```text
.
├── AGENTS.md # Constitution dành cho Agent: vai trò, phạm vi, quyền tool
├── CLAUDE.md # Bộ nhớ dự án và kiến trúc
├── CONSTITUTION.md # Hard governance rule và quality gate
├── .agentignore # Tệp cần bỏ qua để giữ context sạch
├── .claude/skills/ # Slash command SDD/ADD, Git và technical skill
├── .sdd/
│ ├── README.md # Feature registry
│ ├── architecture-profile.md # Binding công nghệ, evidence và artifact gate
│ ├── shared_context.md # State và API contract dùng chung
│ ├── mcp-config.yaml # MCP access control theo Agent
│ ├── template-version.md # Version template đã adopt; do adopt/update scripts quản lý
│ ├── constraints/ # Global, business và safety constraints
│ ├── reviews/ # Report và review ngoài feature
│ ├── rfcs/ # RFC thay đổi governance
│ ├── updates/ # Staged governance files chờ merge (tạm thời sau update)
│ └── features/ # Bộ CONTEXT, SPEC, PLAN, TASKS của từng feature
├── docs/
│ ├── sdd-add-guide.md
│ ├── architecture-profile-guide.md
│ └── multi-agent-orchestration-guide.md
├── scripts/
│ ├── adopt.sh / adopt.ps1 # Tích hợp vào repository có sẵn
│ ├── update.sh / update.ps1 # Cập nhật template từ nguồn gốc
│ ├── self-heal.sh # Test, sửa có giới hạn và Human review
│ └── start-claude.sh / .ps1 # Chế độ --dangerously-skip-permissions
├── src/ # Mã nguồn thực thi
└── tests/ # Test suite
```

---

## 3. Nguyên tắc kiến trúc cốt lõi

- **Spec-as-Code:** Đặc tả được lưu trong Git ở Markdown có cấu trúc để con người và Agent cùng đọc/ghi.
- **EARS Notation:** Functional Requirement trong `SPEC.md` phải dùng EARS: Ubiquitous, Event-driven, State-driven, Optional hoặc Unwanted.
- **Fix the Spec, not the Code:** Khi test thất bại vì requirement thiếu, bổ sung Spec rồi mới thay đổi behavior.
- **Architecture Profile Gate:** `CONTEXT.md` và `SPEC.md` có thể core-only; `PLAN.md`, `TASKS.md`, `/add-execute` và `/sdd-layer-edit` phải dừng khi thiếu binding hoặc exact verification command cần thiết.
- **Template Update:** Repo đã adopt theo dõi version template tại `.sdd/template-version.md`. Dùng `scripts/update.sh` (Linux/macOS) hoặc `scripts/update.ps1` (Windows) để nhận thay đổi mới từ template nguồn; dùng `/sdd-template-update --check` để xem version drift và `/sdd-template-update --review` để AI hướng dẫn merge governance files.

---

## 4. Quy ước kỹ thuật và anti-pattern

### 4.1 Quy ước

- **Tên:** Tệp dùng kebab-case (`order-repository.ts`); class, interface và type dùng PascalCase (`OrderRepository`, `OrderEntity`).
- **EARS tagging:** Function/method thực thi business rule phải có JSDoc `@ears .sdd/features/{slug}/SPEC.md#REQ-XXX`.
- **Dependency direction:** Interface gọi usecase; usecase phụ thuộc port; infra triển khai port. Domain không phụ thuộc adapter hay third-party package.

### 4.2 Anti-pattern cần tránh

- Không truy cập DB trực tiếp từ controller/interface.
- Không dùng magic number inline; đưa vào constant hoặc configuration đã approved.
- Không vá code trực tiếp khi Spec không khớp; quay lại `.sdd/features/{slug}/SPEC.md` trước.
- Không thêm framework, ORM, package, migration hoặc command ngoài Architecture Profile đã approved.

---

## 5. Hệ thống skill — tạo mới hay sao chép (generate vs copy)

`/sdd-init` và `/sdd-adopt` **generate** governance files theo tech stack, không copy verbatim từ template. `AGENTS.md` có 8-section canonical structure (Identity, Scope, Tool Permissions, Security Rules, Communication Style, Error Handling, Escalation Protocol, Changelog). `CLAUDE.md` được điền từ project context thực tế. Xem chi tiết tại skill SKILL.md tương ứng.

ADD 4-phase pipeline: Context Setup → Intent Communication → Agentic Execution → Human Review. Human time ≈ 20% (setup + review); AI time ≈ 80% (execute). Xem `docs/sdd-add-guide.md` section 1.3.

## 6. Tài liệu tham chiếu nhanh