# agentmap
[](https://opensource.org/licenses/MIT)
[](https://www.rust-lang.org/)
**Chuẩn bị codebase cho AI agents** bằng cách tạo tài liệu có cấu trúc giúp trợ lý AI hiểu và điều hướng code của bạn hiệu quả hơn.
[🇬🇧 English](README.md)
## Công Dụng
agentmap quét codebase và tạo ra **cấu trúc tài liệu phân cấp** theo module:
```
.agentmap/
├── INDEX.md # L0: Bảng định hướng toàn cục
├── modules/
│ └── {module-slug}/
│ ├── MODULE.md # L1: Tóm tắt module
│ ├── outline.md # L1: Bản đồ symbol cho module
│ ├── memory.md # L1: Warnings/TODOs theo module
│ └── imports.md # L1: Dependencies cho module
└── files/
└── {file-slug}.md # L2: Tài liệu chi tiết cho file phức tạp (tùy chọn)
```
### Content Hierarchy
| L0 | `INDEX.md` | Bảng định hướng tổng quan theo module | O(modules) |
| L1 | `MODULE.md` | Tóm tắt module, file list, entry points | O(files in module) |
| L1 | `outline.md` | Bản đồ symbol cho file lớn trong module | O(large files) |
| L1 | `memory.md` | Warnings và TODOs theo module | O(markers) |
| L1 | `imports.md` | Phụ thuộc trong module | O(imports) |
| L2 | `files/*.md` | Tài liệu chi tiết cho file phức tạp | O(symbols) |
## Tại Sao Cần?
AI coding assistants gặp khó khăn với codebase lớn vì không thể thấy toàn cảnh. agentmap cung cấp:
- **Điều hướng phân cấp** để AI chỉ load module cần thiết
- **Module detection** để gom file thành các nhóm có ý nghĩa
- **Symbol maps** để biết có gì trong file lớn mà không đọc toàn bộ
- **Scoped context** để docs chỉ chứa thông tin liên quan
## Cài Đặt
### Cài Nhanh (Khuyến nghị)
```bash
### Từ crates.io
```bash
cargo install agentmap
```
### Từ Source
```bash
git clone https://github.com/nguyenphutrong/agentmap
cd agentmap
cargo install --path .
```
### Tải Thủ Công
Tải prebuilt binaries từ [GitHub Releases](https://github.com/nguyenphutrong/agentmap/releases).
## Cách Dùng
### Cơ Bản
```bash
# Tạo docs cho thư mục hiện tại (hierarchical mode - mặc định)
agentmap
# Output ra thư mục tùy chỉnh
agentmap -o docs/ai
# Xem trước mà không ghi file
agentmap --dry-run
# Output chi tiết
agentmap -v
```
### Remote Repositories
```bash
# Phân tích GitHub repo trực tiếp
agentmap github.com/user/repo
agentmap https://github.com/vercel/next.js
# Giới hạn depth cho repo lớn
agentmap --depth 3 github.com/facebook/react
```
### Git Diff Mode
```bash
# Chỉ show các file thay đổi từ branch
agentmap --diff main
# So sánh với commit cụ thể
agentmap --diff HEAD~5
```
### JSON Output
```bash
# Output analysis dưới dạng JSON (cho tooling integration)
agentmap --json > analysis.json
# Kết hợp với flags khác
agentmap --json --depth 2 github.com/user/repo
```
### Options
```
Usage: agentmap [OPTIONS] [PATH]
Arguments:
[PATH] Thư mục đích hoặc GitHub URL [default: .]
Options:
-o, --output <OUTPUT> Thư mục output [default: .agentmap]
-t, --threshold <THRESHOLD> Ngưỡng số dòng cho file "lớn" [default: 500]
-c, --complex-threshold <COMPLEX> Ngưỡng symbol cho L2 file docs [default: 30]
-d, --depth <DEPTH> Max directory depth (0 = unlimited)
--diff <REF> So sánh với git branch/commit
--json Output JSON ra stdout
--check Kiểm tra docs có stale không (exit 1 nếu cần regenerate)
--config <FILE> Đường dẫn config file
--force Force regenerate tất cả modules (bỏ qua cache)
-i, --ignore <IGNORE> Patterns bổ sung để bỏ qua
-l, --lang <LANG> Lọc theo ngôn ngữ
--no-gitignore Không tuân theo .gitignore
--dry-run Xem trước mà không ghi file
-v, --verbose... Tăng mức chi tiết (-v, -vv, -vvv)
-q, --quiet Không hiển thị output
-h, --help In help
-V, --version In version
Commands:
watch Theo dõi file changes và tự động regenerate docs
hooks Quản lý git hooks cho auto-regeneration
init Khởi tạo cấu hình agentmap
update Cập nhật agentmap lên phiên bản mới nhất
```
## Watch Mode
Giữ docs luôn đồng bộ trong quá trình development:
```bash
# Bắt đầu theo dõi changes (regenerate khi save file)
agentmap watch
# Tuỳ chỉnh debounce delay (mặc định: 300ms)
agentmap watch --debounce 500
```
Watch mode tận dụng hệ thống manifest incremental, nên chỉ modules thay đổi được regenerate.
## Git Hooks
Tự động regenerate docs tại các git events quan trọng:
```bash
# Cài hooks (pre-commit, post-checkout, post-merge)
agentmap hooks install
# Gỡ hooks
agentmap hooks remove
# Bỏ qua hooks tạm thời
AGENTMAP_SKIP=1 git commit -m "quick fix"
```
Các hooks được cài:
- **pre-commit**: Regenerate docs và stage `.agentmap/`
- **post-checkout**: Regenerate sau khi đổi branch (chạy nền)
- **post-merge**: Regenerate sau pull/merge (chạy nền)
## Configuration File
Tạo `agentmap.toml` cho cài đặt riêng của project:
```bash
# Tạo config file mặc định
agentmap init --config
# Dùng config tùy chỉnh
agentmap --config custom.toml
```
Ví dụ `agentmap.toml`:
```toml
output = ".agentmap"
threshold = 500
complex_threshold = 1000
ignore = ["*.test.ts", "fixtures/", "__mocks__/"]
[watch]
debounce_ms = 300
```
CLI flags ghi đè giá trị config file.
## MCP Server
agentmap có thể chạy như MCP server cho các AI tools như Claude Desktop và Cursor:
```bash
# Sử dụng npx (không cần cài đặt)
npx agentmap-cli serve --mcp
# Hoặc nếu đã cài global
agentmap serve --mcp
```
**Các tools có sẵn:**
| `regenerate` | Regenerate tài liệu |
| `get_module` | Lấy docs module theo slug |
| `check_stale` | Kiểm tra docs có cần cập nhật |
| `get_outline` | Lấy symbol outline cho file |
**Ví dụ MCP config (Claude Desktop, Cursor, etc.):**
```json
{
"mcpServers": {
"agentmap": {
"command": "npx",
"args": ["agentmap-cli", "serve", "--mcp"]
}
}
}
```
Xem [MCP Server Documentation](docs/mcp-server.vi.md) để biết hướng dẫn cài đặt và tích hợp.
## CI Integration
Validate docs freshness trong CI pipelines:
```bash
# Kiểm tra docs có stale không (exit 0 = fresh, exit 1 = stale)
agentmap --check
# Kết hợp với diff mode
agentmap --check --diff main
```
Ví dụ GitHub Actions workflow:
```yaml
name: Check Agentmap
on: [pull_request]
jobs:
check:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Install agentmap
run: cargo install agentmap
- name: Check docs freshness
run: agentmap --check
```
## Module Detection
agentmap tự động phát hiện module boundary dựa vào quy ước theo ngôn ngữ:
| Rust | `mod.rs`, `lib.rs` | `src/analyze/mod.rs` → module `src-analyze` |
| Python | `__init__.py` | `src/utils/__init__.py` → module `src-utils` |
| JavaScript/TypeScript | `index.{js,ts,tsx}` | `src/components/index.ts` → module `src-components` |
| Any | 5+ source files trong thư mục | `src/helpers/` có 5+ files → implicit module |
### Module Slug Naming
Đường dẫn thư mục được chuyển thành slug bằng dấu gạch ngang:
- `src/analyze/lang` → `src-analyze-lang`
- `lib/utils` → `lib-utils`
## Ví Dụ Output
### INDEX.md (L0 Global)
```markdown
# Project
## Reading Protocol
**Start here**, then navigate to specific modules.
1. Read this INDEX for overview
2. Go to relevant `modules/{name}/MODULE.md`
3. Check module's `outline.md` for large files
4. Check module's `memory.md` for warnings
## Entry Points
- `src/main.rs`
- `src/lib.rs`
## Modules
| [src](modules/src/MODULE.md) | rust | 2 | - | |
| [src/analyze](modules/src-analyze/MODULE.md) | rust | 5 | ⚠️ 2 | |
| [src/generate](modules/src-generate/MODULE.md) | rust | 8 | - | 🔗 |
```
### MODULE.md (L1 Module)
```markdown
# Module: src/analyze
[← Back to INDEX](../../INDEX.md)
**Entry point:** `src/analyze/mod.rs`
## Files
| `src/analyze/graph.rs` | 98 | |
| `src/analyze/parser.rs` | 650 | 📄 |
| `src/analyze/mod.rs` | 10 | |
## Child Modules
- [src-analyze-lang](../src-analyze-lang/MODULE.md)
## Documentation
- [outline.md](outline.md) - Symbol maps for large files
- [memory.md](memory.md) - Warnings and TODOs
- [imports.md](imports.md) - Dependencies
```
### outline.md (L1 Module-Scoped)
```markdown
# Outline: src/analyze
[← MODULE.md](MODULE.md) | [← INDEX.md](../../INDEX.md)
## src/analyze/parser.rs (650 lines)
| Line | Kind | Name | Visibility |
| ---- | ---- | ---- | ---------- |
| 15 | fn | parse_symbols | pub |
| 89 | fn | extract_functions | (private) |
| 156 | struct | ParseResult | pub |
```
### memory.md (L1 Module-Scoped)
```markdown
# Memory: src/analyze
## ⚠️ Warnings
### 🔴 `WARNING` (src/analyze/parser.rs:42)
> Edge case not handled for nested generics
## 🔧 Technical Debt
### 🟡 `TODO` (src/analyze/graph.rs:128)
> Optimize cycle detection algorithm
```
## Supported Languages
| Language | Symbol Extraction | Import Graph | Memory Markers | Module Detection |
|----------|-------------------|--------------|----------------|------------------|
| Rust | ✅ Functions, structs, enums, traits, impls | ✅ | ✅ | ✅ `mod.rs` |
| Python | ✅ Functions, classes, methods | ✅ | ✅ | ✅ `__init__.py` |
| JavaScript/TypeScript | ✅ Functions, classes, arrow functions | ✅ | ✅ | ✅ `index.{js,ts}` |
| Go | ✅ Functions, structs, interfaces, methods | ✅ | ✅ | ✅ implicit |
| Swift | ✅ Functions, classes, structs, enums, protocols | ✅ | ✅ | ✅ implicit |
| Dart | ✅ Functions, classes, mixins, extensions | ✅ | ✅ | ✅ implicit |
| Ruby | ✅ Methods, classes, modules | ✅ | ✅ | ✅ implicit |
| C# | ✅ Methods, classes, structs, interfaces | ✅ | ✅ | ✅ implicit |
| Java | ✅ Methods, classes, interfaces, enums | ✅ | ✅ | ✅ implicit |
## Memory Markers
agentmap trích xuất các comment patterns sau:
| Pattern | Category | Priority |
|---------|----------|----------|
| `TODO`, `FIXME`, `XXX`, `BUG`, `HACK` | Technical Debt | Medium |
| `WARNING`, `WARN` | Warnings | High |
| `SAFETY`, `INVARIANT` | Safety | High |
| `RULE`, `POLICY` | Business Rules | High |
| `DEPRECATED` | Technical Debt | High |
| `NOTE` | Notes | Low |
## Tích Hợp với AI Tools
### Claude Code / Cursor
Thêm vào AI instructions của project:
```
Trước khi làm việc với codebase này, đọc:
1. .agentmap/INDEX.md - tổng quan và điều hướng module
2. Navigate to module's MODULE.md để biết chi tiết
3. Kiểm tra module's memory.md trước khi edit
4. Consult module's outline.md để điều hướng file lớn
```
### GitHub Copilot
Include `.agentmap/` trong workspace context.
### JSON Integration
Cho programmatic access:
```bash
agentmap --json | jq '.modules[] | {slug, file_count, warning_count}'
```
JSON output gồm:
- `modules[]` - Array module metadata (slug, path, file_count, warning_count, symbol_count, is_hub)
- `files[]` - Tất cả scanned files và metadata
- `memory[]` - Tất cả memory markers và locations
- `entry_points[]` - Detected entry points
- `hub_files[]` - Files được import bởi 3+ others
## Development
```bash
# Chạy tests
cargo test
# Chạy với verbose output
cargo run -- -vv .
# Kiểm tra issues
cargo clippy
```
## License
MIT License - xem [LICENSE](LICENSE) để biết chi tiết.