Hướng dẫn cho AI Agent

Trang này dành cho người muốn hiểu cách agent dùng repo. Agent tự đọc CLAUDE.md (ở root repo), không cần đọc trang này.

Tóm tắt

Repo này được thiết kế để AI agent đọc Markdown + JSON, không bao giờ đọc HTML. Site này (Astro Starlight) chỉ phục vụ người. Agent có 3 entry point riêng:

1. CLAUDE.md — quy tắc nền tảng
2. docs/INDEX.md — bản đồ feature
3. /llms.txt và /llms-full.txt — chuẩn llmstxt.org

6 cơ chế tối ưu cho agent

#	Cơ chế	Chi tiết
a	Không bao giờ đọc HTML	Đọc .md + .json từ docs/
b	Entry point 3 tầng	CLAUDE.md → INDEX.md → llms.txt
c	Per-feature isolation	Load đúng folder, không load toàn bộ
d	Impact map tự động	docs/impact-map.json cho dependency reasoning
e	Slash commands	/new-spec, /load-feature, /check-impact
f	Skills (guardrails)	6 skill trong .claude/skills/

6 skills kiểm soát thao tác agent

Skill	Trigger	Mục đích
feature-create	”tạo feature mới”	Scaffold đúng template, 9 heading, validate
feature-edit	”sửa feature X”	Bảo toàn 9 heading, gợi ý impact-check
meta-update	”đổi status X”	Validate status transition
impact-check	”ảnh hưởng feature nào”	Liệt kê deps + impacts + reverse_impacts
scope-guard	User yêu cầu viết code plan / tech detail	Từ chối + chỉ về repo source
validate-docs	”validate”, “check”	Lint + schema + sync

Quy ước agent PHẢI tôn trọng

1. 9 heading ## trong spec.md là bất biến — không thêm, không đổi tên, không đổi thứ tự.
2. meta.json validate theo JSON Schema — _schemas/feature-meta.schema.json.
3. Scope-guard ưu tiên cao nhất — kể cả khi user yêu cầu viết code plan vào repo này, agent vẫn từ chối.
4. Không sửa site/ thủ công — đó là build output.

Endpoint cho agent

Path	Mục đích
/llms.txt	Index ngắn cho agent (chuẩn llmstxt.org)
/llms-full.txt	Toàn bộ spec concatenated (cho khi cần load all-in-one)
/features.json	Aggregate metadata cho client-side scripting
/impact-map.json	Dependency graph machine-readable

Test agent có đọc đúng không?

Trong môi trường dev:

Hỏi: "Hiểu feature auth-otp-login và liệt kê acceptance criteria"

Agent nên:

1. Đọc CLAUDE.md
2. Đọc docs/INDEX.md
3. Đọc docs/features/auth-otp-login/spec.md + meta.json
4. KHÔNG đọc site/

Nếu agent đọc site/ hoặc bịa heading mới → cần điều chỉnh CLAUDE.md hoặc skill description.