Documentation Index

Overview

Cập nhật Documentation Index trong README.md và CLAUDE.md khi docs/ thay đổi. KHÔNG hardcode file names — luôn scan và sync dynamically.

Core Principle

Documentation Index = Source of Truth

Indexes phải phản ánh thực tế trong docs/ directory, không phải danh sách files tĩnh. Mỗi khi thêm/xóa/di chuyển files → cập nhật indexes ngay.

When to Use

✅ Tạo file .md mới trong docs/        → Update indexes
✅ Di chuyển/rename file docs          → Update references
✅ Tổ chức lại docs/ structure         → Reorganize indexes
✅ Xóa file documentation              → Remove from indexes

Dynamic Workflow

Step 1: Scan docs/ reality

bash
1# Liệt kê tất cả .md files hiện có
2find docs -name "*.md" -type f | sort

Expected output pattern:

docs/CODING_STANDARDS.md
docs/DEPLOYMENT.md
docs/GETTING_STARTED.md
docs/SETUP.md
docs/TECH_STACK.md
docs/USERS.md

Step 2: Detect missing files in indexes

bash
1# Check CLAUDE.md index
2grep -E "\`docs/.*\.md\`" CLAUDE.md | sed 's/.*`\(.*\)`.*/\1/' | sort > /tmp/claude_docs.txt
3find docs -name "*.md" -type f | sort > /tmp/actual_docs.txt
4diff /tmp/claude_docs.txt /tmp/actual_docs.txt

Output interpretation:

• Lines starting with < → File có trong index nhưng KHÔNG có trong docs/ (xóa khỏi index)
• Lines starting with > → File có trong docs/ nhưng THIẾU trong index (thêm vào index)

Step 3: Categorize files dynamically

Classification by filename pattern:

Algorithm:

1. Scan tất cả files trong docs/
2. Classify theo pattern và location (core vs modules/)
3. Sắp xếp theo priority trong mỗi category
4. Generate entries cho CLAUDE.md và README.md

Step 4: Update CLAUDE.md Documentation Index

Format:

markdown
1## Documentation Index (Tra cứu nhanh)
2
3| Chủ đề                     | Vị trí                      |
4| -------------------------- | --------------------------- |
5| [Generated dynamically]    | `docs/FILE.md`              |

Link text generation rules:

• SETUP.md → "Hướng dẫn khởi động"
• GETTING_STARTED.md → "Hướng dẫn chi tiết"
• CODING_STANDARDS.md → "Chuẩn code"
• PROJECT_STRUCTURE.md → "Cấu trúc dự án"
• DESIGN_ADN.md → "Design system / tokens"
• TECH_STACK.md → "Công nghệ sử dụng"
• DEPLOYMENT.md → "Triển khai"
• FAQ.md → "FAQ"
• modules/*.md → Tên topic (VD: "Hệ thống người dùng & rank" cho AUTH.md)
• Other files → Tên file without extension, Title Case

Step 5: Update README.md sections

Section structure:

markdown
1### Bắt đầu
2- **[Link Text](docs/FILE.md)** - Short description
3
4### Phát triển
5- **[Link Text](docs/FILE.md)** - Short description
6
7### Operations
8- **[Link Text](docs/FILE.md)** - Short description

Description generation (infer from filename):

• SETUP.md → "Clone, permissions, verify environment"
• GETTING_STARTED.md → "Cài đặt chi tiết"
• CODING_STANDARDS.md → "Conventions, patterns"
• DESIGN_ADN.md → "Design tokens, Brutalist style"
• TECH_STACK.md → "Dependencies chính xác"
• PROJECT_STRUCTURE.md → "Tổ chức thư mục"
• DEPLOYMENT.md → "Cấu hình production, vận hành"
• FAQ.md → "Troubleshooting"
• modules/AUTH.md → "Hệ thống phân quyền, test accounts"

Step 6: Verify consistency

bash
1# 1. Count files in docs/
2DOC_COUNT=$(find docs -name "*.md" -type f | wc -l)
3
4# 2. Count entries in CLAUDE.md index
5CLAUDE_COUNT=$(grep -c "\`docs/.*\.md\`" CLAUDE.md)
6
7# 3. Count entries in README.md
8README_COUNT=$(grep -c "\](docs/.*\.md)" README.md)
9
10echo "Docs: $DOC_COUNT | CLAUDE.md: $CLAUDE_COUNT | README.md: $README_COUNT"

Expected: All counts should be equal (± reasonable margin for internal references)

Step 7: Commit changes

bash
1git diff CLAUDE.md README.md  # Review
2git add CLAUDE.md README.md
3git commit -m "docs: sync documentation index với docs/ directory"

Common Patterns

Adding new documentation file

bash
1# 1. Create file
2touch docs/NEW_TOPIC.md
3
4# 2. Scan to detect
5find docs -name "*.md" -type f | sort
6
7# 3. Classify → Determine section
8# If NEW_TOPIC.md → Core dev doc → "Phát triển" section
9
10# 4. Update CLAUDE.md
11| New Topic | `docs/NEW_TOPIC.md` |
12
13# 5. Update README.md
14### Phát triển
15- **[New Topic](docs/NEW_TOPIC.md)** - Description
16
17# 6. Verify & commit

Moving file to modules/

bash
1# 1. Move file
2git mv docs/USERS.md docs/modules/AUTH.md
3
4# 2. Update ALL references
5git grep -l "docs/USERS.md" | xargs sed -i 's|docs/USERS.md|docs/modules/AUTH.md|g'
6
7# 3. Reclassify → Core → Module
8# CLAUDE.md: Move entry from Development → Operations
9# README.md: Move link from "Phát triển" → "Operations"
10
11# 4. Verify no old paths remain
12git grep "docs/USERS.md" .  # Should return nothing
13
14# 5. Commit
15git add -A && git commit -m "docs: move USERS.md → modules/AUTH.md"

Deleting documentation

bash
1# 1. Remove file
2git rm docs/OBSOLETE.md
3
4# 2. Remove from CLAUDE.md index
5# Delete the row for OBSOLETE.md
6
7# 3. Remove from README.md
8# Delete the link for OBSOLETE.md
9
10# 4. Verify no dangling references
11git grep "OBSOLETE" CLAUDE.md README.md  # Should return nothing
12
13# 5. Commit
14git commit -m "docs: remove obsolete OBSOLETE.md"

Anti-Patterns

❌ Hardcoded file lists

markdown
1## Files to include:
2- SETUP.md
3- GETTING_STARTED.md
4- CODING_STANDARDS.md

Why wrong: List becomes stale immediately after any change.

✅ Dynamic scanning

markdown
1## How to scan:
2find docs -name "*.md" -type f | sort

Why right: Always reflects current state.

❌ Manual categorization

If file is X → put here
If file is Y → put there

Why wrong: Doesn't scale, requires updates for each new file.

✅ Pattern-based classification

If filename matches `SETUP.md` pattern → Getting Started (priority 1)
If file in `modules/` directory → Operations

Why right: Works for any file, scalable.

Verification Checklist

Before committing:

• Ran find docs -name "*.md" to scan actual files
• All files in docs/ have corresponding entry in CLAUDE.md index
• All files in docs/ have corresponding link in README.md
• No references to deleted/moved files remain
• Link text is consistent between CLAUDE.md and README.md
• Files are in correct sections (Getting Started / Development / Operations)
• Table alignment correct in CLAUDE.md
• Tested: grep counts match actual file count

Quick Reference Commands

bash
1# Scan docs
2find docs -name "*.md" -type f | sort
3
4# Detect missing in CLAUDE.md
5grep -o "\`docs/[^)]*\.md\`" CLAUDE.md | sort -u
6
7# Detect missing in README.md
8grep -o "\](docs/[^)]*\.md)" README.md | sed 's/](//' | tr -d ')' | sort -u
9
10# Verify all docs are indexed
11find docs -name "*.md" -type f | while read f; do
12  grep -q "$f" CLAUDE.md || echo "MISSING in CLAUDE.md: $f"
13  grep -q "$f" README.md || echo "MISSING in README.md: $f"
14done
15
16# Count check
17echo "Docs: $(find docs -name "*.md" | wc -l) | CLAUDE: $(grep -c '\`docs/' CLAUDE.md) | README: $(grep -c '](docs/' README.md)"

Real-World Examples

Case 1: Added MOCK_API.md

What happened:

bash
1# Created docs/MOCK_API.md
2# Scan detected: 9 files (was 8)
3# Classified: MOCK_API → Development (API-related)
4# Added to CLAUDE.md index
5# Added to README.md "Phát triển" section
6# Commit: a639438

Case 2: Moved USERS.md → modules/AUTH.md

What happened:

bash
1# git mv docs/USERS.md docs/modules/AUTH.md
2# Reclassified: Core doc → Module doc
3# Moved from "Phát triển" → "Operations" in README.md
4# Updated all references with git grep
5# Verified no old paths remain
6# Commit: f40ce42

Key Takeaway

Documentation Index is a mirror, not a catalog.

When docs/ changes → Update indexes immediately. Never maintain hardcoded lists. Always scan dynamically.