project-discovery

Mục tiêu: tạo file discovery.md ở root project — báo cáo kiến trúc đủ sâu để một dev mới đọc xong có thể tự đóng góp. KHÔNG hỏi xác nhận, scan rồi viết.

Format tham chiếu chính: discovery.md ở root claurst (16 sections, ~700 dòng) — nếu có thì đọc trước để bám style.

Nguyên tắc cốt lõi

• Song song tối đa: mọi Glob/Read/Grep độc lập gửi trong 1 message
• Subagent cho mỗi crate/module lớn: dùng Agent (subagent_type=Explore) khi project có >5 crates/packages — mỗi agent 1 module, chạy song song. Tránh nhồi context chính
• Sample, đừng đọc tất: 1 file đại diện/nhóm là đủ. Đừng đọc file > 500 dòng trừ khi là entry point
• Tiếng Việt cho phân tích, tiếng Anh cho code/tên/thuật ngữ
• Số liệu thật: chạy wc -l, git log, cargo metadata, tokei (nếu có) để có con số chính xác — không bịa
• Không tạo file khác: chỉ ghi 1 file duy nhất là discovery.md. Không tạo doc phụ, không update README

Phase 1: Reconnaissance (1 message, song song)

Chạy đồng thời:

Cấu trúc & manifest:

• Glob: package.json, Cargo.toml, go.mod, pyproject.toml, *.csproj, Gemfile, pom.xml, build.gradle*, mix.exs
• Glob: **/Cargo.toml, **/go.mod, **/package.json để phát hiện workspace/monorepo
• Glob top-level: src/*, crates/*, packages/*, apps/*, cmd/*, internal/*, lib/*, app/*

Tài liệu sẵn có:

• Read: README.md, CLAUDE.md, AGENTS.md, ARCHITECTURE.md, discovery.md (nếu tồn tại — đọc để biết format đã có)
• Glob: spec/**/*.md, docs/**/*.md (chỉ list, không đọc hết)

Build & CI:

• Glob: .github/workflows/*, .gitea/workflows/*, Dockerfile*, Makefile, justfile
• Glob: .cargo/config.toml, tsconfig.json, tox.ini, noxfile.py

Git context (Bash, chạy song song):

• git log --oneline -20
• git log --all --format=%an | sort -u | head -20 — số contributor
• git ls-files | wc -l — số file
• git remote -v

Sau Phase 1 phải xác định được: ngôn ngữ chính, build tool, monorepo hay không, số lượng module/crate/package, có spec/docs sẵn không.

Phase 2: Deep dive theo module

Quyết định chiến lược:

• Project nhỏ (<5 modules, <10k LoC): tự đọc trực tiếp, song song hoá Read
• Project lớn (>=5 modules HOẶC >10k LoC): spawn 1 subagent Explore per module, trong 1 message duy nhất

Brief mỗi subagent (template):

Khám phá crate/package <tên> tại <path>. Cần biết:

1. Vai trò trong hệ thống (1-2 câu)
2. Các file/module chính, mỗi cái làm gì (bullet list)
3. Public API quan trọng nhất (struct/trait/function tên)
4. Dependency tới crate/package khác trong workspace
5. Patterns đáng chú ý (vd: trait-based abstraction, async, plugin) Đọc tối đa 8 file. Báo cáo dưới 300 từ, tiếng Việt, có dấu.

Nếu project có ngôn ngữ phụ (vd Rust + TS frontend), spawn riêng 1 agent cho mỗi side.

Phase 3: Cross-cutting analysis

Sau khi có dữ liệu module, tự thực hiện (không subagent):

• Dependency graph: từ kết quả Phase 2, vẽ bằng ASCII (kiểu cli ──→ core, api)
• Entry points: tìm main.rs, main.go, index.ts, __main__.py, đọc 50 dòng đầu
• Config & runtime: tìm chỗ load config, env var, secret. Grep dotenv|env::var|os.getenv|process.env
• Testing: Glob **/tests/**, **/*_test.go, **/*.test.ts, **/test_*.py. Đếm và phân loại unit/integration
• Patterns: scan có MCP, plugin system, provider abstraction, hooks, feature flags không (Grep tên đặc trưng)
• Số liệu: nếu có tokei thì chạy, không thì git ls-files | xargs wc -l filter theo extension

Phase 4: Viết discovery.md

Template cố định 16 mục (bám discovery.md mẫu của claurst):

# <PROJECT_NAME> — Deep Discovery Report

> <1 câu mô tả + version + license + quy mô>

## 1. Kiến trúc tổng quan
- ASCII diagram các tầng/module
- Dependency graph

## 2..N. Module/Crate/Package <tên>
- Vai trò
- Cấu trúc file
- Public API chính
- Dependencies
- Pattern đặc trưng

## N+1. Entry point(s)
## N+2. Configuration & Runtime
## N+3. Testing strategy
## N+4. CI/CD
## N+5. Feature flags / build profiles (nếu có)
## N+6. Patterns đáng chú ý
## N+7. Số liệu tổng hợp
- LoC theo ngôn ngữ
- Số file, số module
- Số contributor, commit gần nhất
- Test coverage (nếu detect được)

Quy tắc viết:

• Dùng bảng Markdown cho liệt kê crate/module (cột: tên, role, LoC nếu có)
• Mỗi section có ít nhất 1 code reference dạng path/to/file.rs:42 để user click được
• Không lặp lại README — bổ sung góc nhìn architecture, không phải tutorial
• Không bịa: nếu không kiểm chứng được thì ghi (chưa xác minh) hoặc bỏ qua
• Cuối file thêm dòng: > Generated by project-discovery skill on YYYY-MM-DD

Phase 5: Verification

Sau khi Write discovery.md:

1. Đếm dòng (wc -l discovery.md) — báo cho user
2. Báo cáo cuối: số module phân tích, LoC tổng, file output, 3 phát hiện thú vị nhất (1 câu mỗi cái)

KHÔNG commit, KHÔNG push, KHÔNG mở PR — chỉ ghi file và dừng.

Anti-patterns — đừng làm

Test thực tế

Skill này được phát triển trên repo claurst (Rust monorepo, 12 crates, ~50k LoC). File discovery.md ở root là output tham chiếu — chạy skill lại trên claurst phải tạo ra báo cáo có cấu trúc tương đương (16 sections, có dependency graph, có per-crate breakdown, có số liệu).