Taming agents in the Mercari web monorepo

Mercari · 2025 · 3. Quy mô lớn · Độ khó: Dễ — bài gốc

Một bài trong series Global App (ngoài sheet). Monorepo web: Mercari 2025.

Bối cảnh

Đội web Global dùng nhiều công cụ agent khác nhau (Cursor, Claude Code, GitHub Copilot, Codex CLI), mỗi người tự chọn. Người dùng Cursor và Claude Code viết rule theo định dạng của công cụ mình: công trùng lặp, các bộ rule trôi dần khỏi nhau; người dùng công cụ khác phải lặp lại cùng lời nhắc ở đầu mỗi phiên.

Một tệp ngữ cảnh chung, không ép một công cụ: gộp rule Cursor và Claude thành AGENT.md (RFC của Sourcegraph/Amp), CLAUDE.md và các tệp rule khác thành symlink về đó; sau đổi sang AGENTS.md khi chuẩn được OpenAI và đa số công cụ hỗ trợ.
AGENTS.md là mục lục trỏ tới tệp theo chủ đề: lệnh build/test, code style, kiến trúc (tầng module app/feature/domain/core, chiều phụ thuộc do eslint-plugin-boundaries ép), xác thực, test, quy tắc design system (luôn import từ gói design system, không inline style, dùng token màu). Theo bài, thiếu ngữ cảnh kiến trúc thì output của hầu hết công cụ phải cấu trúc lại toàn bộ.
Tài liệu tự cập nhật: PR thay đổi thiết kế mức cao thì engineer chạy agent trên changeset và thư mục rule để đề xuất sửa rule hoặc chỉ ra chỗ code lệch. Đang làm: agent chạy trên mọi PR, chỉ ra code lệch rule (người hay máy viết), và sinh patch cho rule khi thay đổi cấu trúc là có chủ ý.

Công cụ thay đổi nhanh; thống nhất ngữ cảnh rẻ hơn và bền hơn thống nhất công cụ.

Ngữ cảnh cho agent là tài liệu kiến trúc; giữ một nguồn, nhiều tên gọi.
Rule nào kiểm được bằng máy (ranh giới module) thì để linter ép; tệp ngữ cảnh lo phần còn lại.