Bắt đầu cho BA¶

Trang này gom toàn bộ luồng một BA làm việc với repo vào một chỗ: từ lúc nhận máy mới đến lúc mở Merge Request. Mỗi mục có link sang luật/skill chi tiết.

Bạn không cần biết code

BA làm việc bằng cách gõ chat cho Claude — Claude viết & sửa file, bạn rà và chốt. Bạn chỉ cần biết vài lệnh git/terminal ở trang này, copy là chạy.

0. Mô hình cần nhớ trước¶

Repo này là một nguồn, hai người đọc:

Nguồn = file .md trong docs/ → chỉ Claude viết/sửa qua chat.
Hiển thị = trang web MkDocs → bạn mở trình duyệt để xem (không sửa trực tiếp được).

→ Muốn đổi nội dung: quay lại gõ chat cho Claude, xem lại bản render, lặp tới khi ưng. Đừng sửa tay file .md thô. Chi tiết: đọc CLAUDE.md ở gốc repo.

BA tự do trong việc của mình — nhưng không sửa 'luật chung'

Bạn thoải mái làm trong docs/, ui-mockups/, cong-viec/. Nhưng luật chung — CLAUDE.md, rules/, .claude/ (skill, agent, hook) — chỉ Quản lý được sửa. Một hook (.claude/hooks/guard-files.py) sẽ chặn cứng nếu Claude trên máy bạn định sửa các file này (nhận diện qua email git). Muốn đổi "cách làm"? Đừng sửa tay — đề xuất với Quản lý, Quản lý chỉnh & commit. Chi tiết: rules/phoi-hop-nhom.md mục 9.

1. Chuẩn bị máy (làm một lần)¶

Cài Claude Code trên máy (xem hướng dẫn nội bộ của đội).
Clone repo về máy:
```
git clone https://code.longdo.com.vn/root/ba-docs.git
cd ba-docs
```
Skill & agent đi kèm trong .claude/ — clone xong là dùng được ngay, không cần cài gì thêm.

Khai báo bạn là ai (Claude dựa vào đây để biết task nào của bạn):

git config user.name  "Họ Tên Của Bạn"
git config user.email "email-dung-trong-roster"   # đúng email ở cong-viec/thanh-vien.md

Email phải khớp roster

Email git của bạn phải trùng với dòng của bạn trong cong-viec/thanh-vien.md. Nếu chưa có/không khớp, báo Quản lý thêm bạn vào roster — nếu không Claude sẽ không nhận diện được bạn là BA nào. Cơ chế đầy đủ: rules/phoi-hop-nhom.md.

Mở Claude Code tại thư mục ba-docs. Mỗi phiên Claude tự đọc CLAUDE.md + rules/ nên luôn làm theo chuẩn chung của đội.

2. Lấy việc mới nhất¶

Trước mỗi buổi làm, kéo bản mới về:

git checkout main && git pull

3. Nhận việc hoặc giao việc¶

Đội phối hợp qua thư mục cong-viec/: một task = một file .md = một nhánh git. Có hai vai, mỗi vai một skill:

Bạn đang làm gì	Gọi skill	Skill sẽ làm
Nhận việc được giao	`lam-task`	Tìm task `giao-cho` đúng id của bạn, tạo nhánh, làm đúng phạm vi, cập nhật trạng thái, mở MR.
Giao việc cho cả đội	`phan-cong`	Bẻ một dự án thành các task, gán người + phạm vi file không chồng nhau, ghi file vào `cong-viec/`, push.

Vai giao việc cố định: chỉ BA điều phối mainp (Nguyễn Phương Mai) dùng phan-cong. mainp quyết định ai tham gia từng giai đoạn và chia task theo đó — có giai đoạn chỉ một người (mainp giao cho một BA bất kỳ, không nhất thiết là chính mình), có giai đoạn 2–3 người thì chia đều. Việc giao là của mainp, còn người làm là ai do mainp quyết. Các BA còn lại nhận việc bằng lam-task. Quản lý duyệt MR.

Trong Claude, chỉ cần gõ tên skill và mô tả, ví dụ:

"Dùng skill lam-task cho tôi" — Claude tự tìm task của bạn và bắt đầu.

Luật phối hợp đầy đủ: rules/phoi-hop-nhom.md · bảng phân công: cong-viec/README.md.

4. Viết tài liệu¶

Tùy việc, gọi skill phù hợp — Claude bám template & quy ước sẵn:

Cần làm	Skill	Kết quả
Đặc tả yêu cầu một tính năng/dự án (mục tiêu, user story, tiêu chí nghiệm thu)	`viet-prd`	`docs/<du-an>/prd.md`
Viết tài liệu hệ thống (kiến trúc, nghiệp vụ, CSDL, API…)	`viet-tai-lieu`	File `.md` trong `docs/<du-an>/`

Quy ước viết: rules/tai-lieu.md. Cách làm bảng đẹp có tooltip: Bộ component & style.

5. Dựng giao diện mẫu (mockup)¶

Cần làm	Skill / Agent	Ghi chú
Dựng mockup HTML cho một màn hình	skill `dung-mockup`	Quy trình từng bước (chung cho web & app)
Chuẩn brand & component — giao diện web	skill `thiet-ke-mockup`	Design token, thư viện component web
Chuẩn brand & component — app mobile	skill `thiet-ke-mockup-app`	Flutter / Material 3, xuất HTML trong khung điện thoại
Dựng nhiều màn cùng lúc	agent `mockup-designer`	Sinh hàng loạt
Soát mockup trước khi duyệt	agent `mockup-reviewer`	Chỉ đọc & báo lỗi

Web hay app? dung-mockup tự định tuyến theo loại task: mockup → chuẩn web (thiet-ke-mockup), mockup-app → chuẩn app mobile (thiet-ke-mockup-app). Người giao việc đặt đúng loai trong task; bạn không phải chọn tay.

Mockup lưu ở ui-mockups/<du-an>/. Quy ước: rules/giao-dien.md.

Mỗi mockup duyệt xong → kèm 'đặc tả màn' cho Dev

Sau khi dựng mockup, Claude đọc lại mockup và sinh bản nháp đặc tả màn (liệt kê từng thành phần: kiểu, bắt buộc hay không, nguồn dữ liệu, ràng buộc) đặt cạnh tài liệu ở docs/<du-an>/giao-dien/<man>.md. Bạn rà & sửa cho đúng nghiệp vụ thật (API/entity, ràng buộc) — đây là phần Dev dựa vào để code. Mẫu: templates/dac-ta-man-hinh.md; bước chi tiết: skill dung-mockup Bước 5.

6. Xem kết quả & rà soát file trước khi đẩy¶

Tài liệu chỉ 'xong' khi hiển thị đúng trên web

Luôn xem bản render thật trước khi commit, đừng tin vào file .md thô.

Xem tài liệu (trang web MkDocs):

pip install -r requirements.txt   # lần đầu
mkdocs serve                      # → http://localhost:8000

Xem mockup (chia sẻ nội mạng cho cả đội):
```
cd ui-mockups && python -m http.server 8080
```
Mở http://<ip-may-ban>:8080 từ máy khác trong công ty.

Rà lại đúng những file đã đụng

Trước khi đẩy, Claude tự chạy git status + git diff để rà lại chính xác các file đã tạo/sửa, đối chiếu đều nằm trong pham-vi của task (không lỡ đụng file ngoài phạm vi, không file rác/secret), rồi trình danh sách cho bạn xem ở cổng xác nhận. Chi tiết: skill lam-task Bước 5.

7. Đẩy lên & mở Merge Request¶

Claude chờ bạn xác nhận mới commit/push

Claude không tự commit/push. Khi làm xong, Claude trình kết quả và hỏi "task đã hoàn thành chưa?". Chỉ khi bạn xác nhận thì Claude mới commit, đẩy nhánh và mở MR. Muốn sửa thêm thì cứ nói, chưa cần đẩy.

Khi nội dung đã ổn và bạn đã xác nhận, Claude đẩy nhánh lên rồi mở MR:

git pull --rebase origin main          # giảm xung đột với việc mới
git push -u origin ba/<id>/<task-id>   # đẩy nhánh task

Lên GitLab mở Merge Request vào main, gán Quản lý duyệt.

BA không tự merge

Bạn dừng ở bước mở MR. Quản lý duyệt MR & xử lý conflict rồi mới merge vào main. Đừng commit thẳng vào main, đừng force-push. Quy ước commit: rules/git-commit.md.

Đi đâu khi cần biết thêm¶

Muốn hiểu	Đọc
Các câu lệnh git & terminal cần chạy	Lệnh thường dùng
Quy trình & triết lý tổng thể	`CLAUDE.md` (gốc repo)
3 BA phối hợp qua Git, nhánh, MR	`rules/phoi-hop-nhom.md`
Bảng phân công việc	`cong-viec/README.md`
Cách viết tài liệu	`rules/tai-lieu.md`
Bộ class hiển thị (bảng, badge, tooltip)	Bộ component & style
Cách dựng mockup	`rules/giao-dien.md`
Thêm một dự án mới vào repo	Thêm dự án mới
Quy ước commit	`rules/git-commit.md`
Không lộ bí mật	`rules/bao-mat.md`