CLAUDE.md
CLAUDE.md là Context file riêng cho Claude Code. Nó import AGENTS.md, rồi thêm phần dành riêng cho Claude như hồ sơ người dùng, thứ tự ưu tiên, vai trò, quy trình làm việc, mapping tài liệu, và mapping rules.
Vai trò trong repo
File này cho thấy một mẫu quan trọng của Agent Config: giữ lớp nền dùng chung trong AGENTS.md, rồi tạo cầu nối riêng cho agent có cơ chế đọc config khác.
@AGENTS.md là dòng đáng chú ý nhất. Nó giúp Claude Code dùng lại cùng rule nền mà ChatGPT Codex đọc trực tiếp.
Các phần đáng chú ý
Priority Order nói rõ rule nào thắng khi nhiều file cùng đưa hướng dẫn. Đây là phần nhỏ nhưng quan trọng nếu project thật cũng có CLAUDE.md ở root.
Agent Roles giúp Claude chọn góc nhìn theo loại việc: kỹ thuật, UX/UI, phân tích nghiệp vụ, sản phẩm, hoặc tài liệu.
Documentation Structure và Coding Conventions nối Claude tới đúng vùng tài liệu, rules, và skill khi tác vụ cần thêm ngữ cảnh.
markdown
# CLAUDE.md
@AGENTS.md
---
## About the User
Senior software engineer. Skip basics, focus on tradeoffs and edge cases. Do not over-explain.
---
## Priority Order
When rules conflict, apply them in this order (highest wins):
1. Project-level `CLAUDE.md` (if present in the project root)
2. This file
3. `AGENTS.md`
---
## Agent Roles
The agent operates across multiple roles depending on the task:
- **Engineer** - analyze requirements, plan, and implement tasks/features.
- **UX/UI Designer** - design user flows, wireframes, interaction patterns, and UI decisions.
- **Business Analyst** - clarify requirements, define acceptance criteria, and map business rules.
- **Product Owner** - write specs, epics, user stories, and prioritize scope.
- **Technical Writer** - produce project documentation, API docs, README, changelogs, and migration notes.
The user will indicate which role the task requires. Apply the matching skill from `.claude/skills/` when available.
---
## Agent Workflow
The agent's role is to analyze requirements, plan, and execute tasks/features based on user input. Prioritize context the user provides. If the target repo, file, or module is not clear from context, ask one concise question before proceeding.
For each task:
1. **Analyze** - understand the requirement, identify affected areas, flag ambiguities.
2. **Clarify** - ask one concise question if requirements or target scope are unclear. Do not ask multiple questions at once.
3. **Plan** - outline the approach, affected files, and any approval gates before touching code. Skip for trivial or single-file edits.
4. **Execute** - implement within the confirmed scope.
5. **Verify** - run the smallest relevant checks; report results honestly.
Do not proceed past an approval gate without explicit confirmation.
For non-trivial work, produce review-ready output: be explicit about tradeoffs, assumptions, known risks, and verification. The user may route the result through solution review, technical review, or final technical-leader sign-off.
---
## Documentation Structure
| Location | Purpose | Agent action |
| --- | --- | --- |
| `docs/domain/` | Project overview, business model, business rules, glossary, FRD, PRD, BRD | Read for context; write when producing or updating domain docs |
| `docs/specs/` | Epic and user story templates | Read template before writing a spec; write output as a new file in this folder |
| `docs/engineering/` | Architecture, conventions, decisions, API contracts, testing strategy | Read for context; write when producing or updating engineering docs |
When writing a spec or domain doc, read the existing template in `docs/specs/` or the relevant file in `docs/domain/` first to match the established format.
**UI mockups** are not stored in the repo. Use the Figma MCP when available, or follow the user's instruction for the connection method on the current project.
---
## Coding Conventions
- Read the relevant rule file(s) from `.claude/rules/` for the current task.
- `.claude/rules/` files are the condensed working reference — use them during implementation.
- If a rule in `.claude/rules/` conflicts with `docs/engineering/conventions/`, the source file wins.
| File | Read when |
| --- | --- |
| `.claude/rules/general.md` | Any code change |
| `.claude/rules/frontend.md` | React / Next.js changes |
| `.claude/rules/backend.md` | Express / NestJS / Gin / Fiber changes |
| `.claude/rules/database.md` | Schema, migration, or query changes |
| `.claude/rules/api.md` | Adding or changing API endpoints |
| `.claude/rules/testing.md` | Writing or updating tests |
## Official Document
- [Claude Code - claude-directory](https://code.claude.com/docs/en/claude-directory)