PHẦN 2 — CẤU TRÚC & CẤU HÌNH

2.1 Mô hình hai repo trong một GitLab Group

GitLab Group: /thaco-voc
├── thaco-voc-docs        ← BA + PM sở hữu, DEV ghi được trong thư mục spec
└── thaco-voc-src         ← DEV sở hữu

DEV clone cả hai cạnh nhau, mở Claude Code ở thư mục cha:

~/work/thaco-voc/          ← mở Claude Code ở ĐÂY
├── CLAUDE.md
├── thaco-voc-docs/
└── thaco-voc-src/

2.2 Cây thư mục repo tài liệu (`-docs`)

thaco-voc-docs/
├── CLAUDE.md
├── README.md
├── .claude/
│   ├── roles/{ba,dev,pm}.md
│   └── commands/
│       ├── clarify.md          # /clarify    — sinh câu hỏi làm rõ
│       ├── prd.md              # /prd        — viết PRD theo template
│       ├── spec.md             # /spec       — sinh spec từ PRD
│       ├── trace.md            # /trace      — đối chiếu AC ↔ test
│       ├── dor-check.md        # /dor-check  — kiểm điều kiện giao DEV
│       └── weekly.md           # /weekly     — sinh báo cáo tuần
├── .gitlab/
│   ├── issue_templates/{Feature,Bug,Change-Request}.md
│   └── merge_request_templates/Default.md
├── CODEOWNERS
│
├── 00-inbox/                   # [BA+PM ghi] nguyên liệu thô
│   ├── meetings/ · emails/ · attachments/
│
├── 01-analysis/                # [BA ghi]
│   ├── open-questions.md · clarification-log.md · glossary.md
│   ├── as-is/ · to-be/
│
├── 02-requirements/            # [BA ghi]
│   ├── srs.md · business-rules.md
│   ├── prd/
│   │   ├── FE-001-quan-ly-tien-do-giao-xe.md
│   │   └── _template/prd-template.md
│   ├── spec/
│   │   ├── FE-001-spec.md
│   │   └── _template/spec-template.md
│   └── change-requests/
│
├── 03-design/                  # [BA + DEV]
│   ├── architecture/ · data-model/ · api-contract/ · ui-ux/
│
├── 04-dev/                     # [DEV ghi]
│   ├── tech-notes/ · adr/ · conventions.md
│
├── 05-qa/                      # [PM ghi, DEV bổ sung]
│   ├── test-cases/ · uat/ · defects/
│
├── 06-reports/                 # [PM ghi]
│   ├── raw/ · weekly/ · sprint/
│   ├── metrics-definition.md
│   └── trace-matrix.md
│
└── 99-archive/

2.3 Ranh giới ghi

Ký hiệu: ✍️ được ghi · 👁 chỉ đọc · ❌ không đụng vào.

Thư mục	BA	DEV	PM
`00-inbox/`	✍️	👁	✍️
`01-analysis/`	✍️	👁	👁
`02-requirements/` (trừ `spec/`)	✍️	👁	👁
`02-requirements/spec/`	✍️	✍️	👁
`03-design/`	✍️	✍️	👁
`04-dev/`	👁	✍️	👁
`05-qa/`	👁	✍️	✍️
`06-reports/`	👁	👁	✍️
repo source	❌	✍️	👁

Thư mục spec/ là ngoại lệ có chủ ý — spec là hợp đồng giữa BA và DEV, nên cả hai phải chạm được vào nó. Đổi lại, mọi thay đổi trong thư mục này bắt buộc qua MR có BA approve:

# CODEOWNERS
02-requirements/spec/   @ba @dev
02-requirements/        @ba

2.4 Quy ước đặt tên

Loại	Quy ước	Ví dụ
Feature	`FE-<3 số>-<kebab-case>`	`FE-001-quan-ly-tien-do-giao-xe`
Acceptance Criteria	`FE-<3 số>-AC-<2 số>`	`FE-001-AC-03`
Change Request	`CR-<3 số>-<kebab-case>`	`CR-001-quy-trinh-ra-vao-xuong`
Bug	`BUG-<3 số>`	`BUG-014`
Business Rule	`BR-<2 số>`	`BR-07`
Open Question	`OQ-<3 số>`	`OQ-014`
ADR	`ADR-<3 số>-<quyết định>`	`ADR-002-cache-strategy`
Branch	`feature/FE-001-slug`
Commit	`<type>(FE-001): <mô tả>`	`feat(FE-001): add duplicate VIN check`
Tên test	`[FE-001-AC-03] <mô tả>`	`[FE-001-AC-03] should_reject_duplicate_vin`

Mã cấp AC là thay đổi quan trọng nhất của v2.0. FE-001 quá thô để đối chiếu — phải xuống tới từng tiêu chí nghiệm thu thì mới trả lời được câu hỏi "yêu cầu này đã có code và test chưa".

2.5 Cấu hình ba AI

Cơ chế nạp context — ba tầng:

Tầng	File	Nội dung	Commit?
Dự án	`./CLAUDE.md`	Luật chung, ranh giới ghi, ID convention	✅
Vai trò	`.claude/roles/{ba,dev,pm}.md`	Nhiệm vụ và quy trình từng vai trò	✅
Cá nhân	`~/.claude/CLAUDE.md`	Khai báo vai trò	❌

Mỗi người thêm vào ~/.claude/CLAUDE.md trên máy mình:

Trong dự án thaco-voc, vai trò của tôi là BA.
Trước khi làm bất kỳ việc gì trong dự án này, đọc `.claude/roles/ba.md` và tuân thủ tuyệt đối.

Header metadata — mọi file trong 02-requirements/, 04-dev/, 05-qa/:

---
id: FE-001
title: Quản lý tiến độ giao xe
owner: BA | DEV | PM
status: draft | reviewing | baselined | approved | changed | deprecated
version: 1.2
gitlab_issue: "#42"
updated: 2026-07-23
source: 00-inbox/meetings/2026-07-21-kickoff.md
---

Riêng file spec thêm ba trường:

prd_baseline: FE-001-v1.0      # tag git của PRD mà spec này dịch ra
approved_by: BA                # ai đã duyệt
approved_at: 2026-07-24

Trường prd_baseline giữ spec không trôi khỏi PRD. Khi PRD lên version mới qua CR, trường này lộ ra ngay spec đang bám vào bản cũ.

2.6 Quy ước GitLab

Scoped labels:

type::feature   type::bug   type::cr   type::task   type::spike   type::doc

status::draft            ← BA đang soạn PRD
status::clarifying       ← chờ khách hàng trả lời
status::spec             ← ★ MỚI: DEV đang viết spec / BA đang duyệt spec
status::ready-for-dev    ← spec đã duyệt, qua DoR
status::in-dev
status::mr-review
status::qc
status::uat
status::done
status::blocked

owner::ba      owner::dev     owner::pm
prio::P1       prio::P2       prio::P3
module::voc    module::emenu  module::crm

Trạng thái status::spec tách riêng để đo được thời gian nằm ở khâu đặc tả. Nếu khâu này kéo dài bất thường, đó là tín hiệu PRD viết chưa đủ rõ — chẩn đoán được ngay mà không cần hỏi ai.

Trường bắt buộc trên issue:

Trường	Ai điền	Ghi chú
Title	BA	`[FE-001] Quản lý tiến độ giao xe`
Description	BA	Link PRD tại tag baseline + checklist AC ID
Weight	BA + DEV	Story point
Milestone	PM	= Sprint
Estimate	DEV	`/estimate 3d`, chốt sau khi có spec
Spend	DEV	`/spend 4h`, cập nhật hằng ngày
Assignee	PM	1 người duy nhất

Checklist AC trong description — GitLab tự đếm và hiện tiến độ:

## Acceptance Criteria
- [ ] FE-001-AC-01 Hiển thị danh sách xe theo trạng thái giao
- [ ] FE-001-AC-02 Lọc theo khoảng ngày dự kiến giao
- [ ] FE-001-AC-03 Chặn tạo phiếu trùng VIN trong cùng ngày