git:20260824.63449ef to git:20260824.a9d95f4

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

# Project: Starter Template (SDD + ADD Boilerplate)

---

## 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

│ ├── constraints/ # Global, business và safety constraints

│ ├── reviews/ # Report và review ngoài feature

│ ├── rfcs/ # RFC thay đổi governance

│ └── 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

│ ├── 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.

---

## 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.