| name | docs-project |
| description | Cập nhật tài liệu dự án: README, workflow guides, hướng dẫn cài đặt, install scripts, CLAUDE.md. Khác với /docs-update (baseline screen/API sau task) — skill này dành cho project-level docs. Trigger khi: user nói "cập nhật README", "update hướng dẫn cài đặt", "sửa workflow guide", "update install script", "cập nhật CLAUDE.md", "sync project docs", hoặc gõ /docs-project.
|
Skill: /docs-project
Role: Developer / Tech Lead / DevOps
Mục đích: Đồng bộ tất cả tài liệu project-level (README, guides, install scripts, CLAUDE.md) với trạng thái thực tế của codebase.
Phân biệt với /docs-update
| Skill | Dùng cho | Trigger |
|---|
/docs-update | Baseline screen + API docs sau task verify | Sau mỗi task merge |
/docs-project | README, workflow, install, CLAUDE.md | Khi project thay đổi lớn |
Hướng dẫn thực hiện
Bước 1 — Xác định scope
Đọc các file sau để hiểu trạng thái hiện tại:
README.md (hoặc README.vi.md nếu có)CLAUDE.mddocs/workflows/*.mdbin/install.js, setup.sh, setup.ps1 (nếu có)package.json (scripts, version, dependencies)pubspec.yaml (nếu Flutter project).claude/settings.json
Dùng AskUserQuestion tool để hỏi:
Chờ confirm.
Bước 2 — Audit: Tìm nội dung lỗi thời
Với mỗi file trong scope, so sánh nội dung hiện tại với thực tế:
README audit checklist:
CLAUDE.md audit checklist:
Workflow guides audit checklist:
Install scripts audit checklist:
Bước 3 — Đề xuất thay đổi
Với mỗi file cần update, trình bày theo format:
## 📄 [Tên file]
**Vấn đề tìm thấy:**
- [Mô tả nội dung lỗi thời / sai / thiếu]
**Đề xuất thay đổi:**
--- HIỆN TẠI ---
[Nội dung cần xóa/sửa]
--- ĐỀ XUẤT ---
[Nội dung mới]
**Lý do:** [Giải thích ngắn gọn tại sao cần thay đổi]
Nếu cần thêm section mới (không phải sửa): trình bày full nội dung mới, đề xuất vị trí insert.
Chờ confirm từng file trước khi apply.
Bước 4 — Gate: Review từng thay đổi
Dùng AskUserQuestion tool cho mỗi file:
- Nội dung đề xuất: Có chính xác và đủ không?
- Tone/ngôn ngữ: Phù hợp với audience (developer nội bộ / end user / khách JP)?
- Có bỏ sót gì không?
Chờ confirm trước khi ghi file.
Bước 5 — Apply và verify
Sau khi user confirm, apply từng thay đổi:
- Edit files — dùng Edit tool, không rewrite toàn bộ file trừ khi cần thiết
- Verify links — kiểm tra internal links (relative paths) sau khi sửa
- Verify install script — nếu
bin/install.js thay đổi, check danh sách FILES_TO_COPY:
node bin/install.js --dry-run 2>/dev/null || echo "dry-run not supported, review manually"
- Check README quick start — nếu lệnh quick start thay đổi, verify syntax đúng
Bước 6 — Tạo commit
Sau khi tất cả files đã update và verify:
git add README.md CLAUDE.md docs/workflows/ bin/install.js setup.sh setup.ps1
git status
Đề xuất commit message theo convention:
docs: sync project docs với [tên feature/thay đổi]
- README: [tóm tắt thay đổi]
- CLAUDE.md: [tóm tắt thay đổi]
- docs/workflows/: [tóm tắt thay đổi]
- bin/install.js: [tóm tắt thay đổi]
Hỏi user trước khi commit — không tự commit.
Bước 7 — Thông báo team (tuỳ chọn)
Nếu thay đổi ảnh hưởng đến onboarding flow (install script, README quick start), đề xuất:
- Tạo GitLab/GitHub issue để thông báo team re-install
- Post vào channel Slack/Teams tương ứng
- Nếu là breaking change trong
npx install: bump version trong package.json
Nguyên tắc
- Không tự động commit — luôn show diff và chờ confirm
- Edit, không rewrite — giữ lại nội dung đúng, chỉ sửa phần sai
- Verify sau khi sửa — đặc biệt với install scripts và links
- Audience-aware — README cho end user khác với CLAUDE.md cho AI
- Tiếng Việt cho tài liệu nội bộ — README có thể song ngữ nếu có khách JP
