Một từ, một nghĩa
Không mơ hồ với đồng đội, cũng không mơ hồ với agent đang đọc specs.
Vấn đề
Code với AI hỏng theo bốn cách rất dễ đoán
Không cái nào là vấn đề chất lượng model. Tất cả đều là vấn đề ngữ cảnh — mà ngữ cảnh thì kỹ thuật hoá được.
Mỗi phiên lại bắt đầu từ số không
Bạn dán lại đúng đoạn giải thích kiến trúc đó. Hoặc nhét cả repo vào rồi nhìn context window đầy ứ những thứ tác vụ này không bao giờ đụng tới.
Agent sửa cả thứ không nên đụng
Một yêu cầu nhỏ, và nó lặng lẽ refactor ba module bạn chưa từng nhắc tới. Không nêu ranh giới thì cái gì cũng có vẻ trong phạm vi.
Tài liệu chết ngay khi vừa viết xong
Specs lệch khỏi code trong vòng một tuần. Không ai cập nhật nên không ai tin, rồi agent được cho ăn sự thật cũ — một cách rất tự tin.
Nuôi model lại thành việc
Nếu giữ đồng bộ nghĩa là sửa tay tài liệu sau mỗi commit thì sẽ không ai làm. Model phải tự nuôi được, không thì nó chết.
Context-Centric
Mô hình sản phẩm theo context, không theo tài liệu
Context là vùng ranh giới mà trong đó mỗi từ chỉ có đúng một nghĩa. Bên trong bạn mô hình hoá entity và usecase; cạnh giữa các context suy ra từ @mention giữa usecase — không vẽ tay.
- Mỗi context sở hữu ngôn ngữ riêng. "Order" ở Ordering và "Order" ở Delivery có thể mang nghĩa khác nhau mà vẫn an toàn.
- Mọi thay đổi rơi vào đúng một context — nên phạm vi ảnh hưởng của nó tính được, không phải đoán.
- Model xuất ra dspecs.json và Markdown — nó là dữ liệu của bạn, không phải một dòng trong database của ai khác.
Context
Ordering
Order· total, items
Place Orderwrite
List My Ordersread
Context
Delivery
Order· address, courier
Prepare Delivery
Place Order@Prepare Delivery
auto-derived from the @mention — never hand-drawn
Thay đổi nằm gọn một chỗ
DSpecs suy ra thay đổi thật sự chạm tới context nào — bằng duyệt đồ thị, không hỏi LLM.
Ngữ cảnh vừa đủ cho AI
Prompt nhỏ hơn, ít hallucination hơn, không phí context window cho code không liên quan.
Model tự giữ mình trung thực
Linter chỉ ra spec đã lệch hoặc còn rỗng ruột; mọi chữ agent muốn sửa đều quay về dạng đề xuất để bạn duyệt.
Compile & Bàn giao
DSpecs viết specs cho bạn — và giao thẳng tới Claude, Codex, Cursor
Bạn duy trì model; specs là build artifact. Một cú bấm compile ra CLAUDE.md, AGENTS.md, Cursor rules và JSON — kèm Constitution ở đầu — rồi giao qua MCP hoặc CLI.
Một model → mọi định dạng
compile — one model, every format
$ dspecs pull ✓ CLAUDE.md (17.8 KB) ✓ AGENTS.md ✓ .cursor/rules/ (10 files) ✓ dspecs.json ## 0. Project Constitution Stack: Next.js · Prisma · PostgreSQL ## 1. Context: Ordering #### Entity: Customer ⭐ root #### Usecase: Checkout — actor: Buyer
Nối agent — một URL + token
terminal
$ claude mcp add --transport http dspecs \ https://dspecs.com/api/v1/mcp \ --header "Authorization: Bearer dsp_xxx" # 13 tools available: # get_project_overview · get_context # get_usecase · get_specs · search_specs # list_updates · get_update_delta # set_update_status · propose_spec_change # get_sync_plan · import_model_map # finish_code_map · get_mapping_status
Chạy vớiClaude CodeCodex CLICursorGitHub Copilotvà mọi công cụ hỗ trợ MCP
Code Graph
Specs của bạn biết code nằm ở đâu
Mỗi context, entity, usecase đều mang codeRef — file và symbol thật thực thi nó. Agent tự map repo; bạn duyệt phần lệch. Không bao giờ xoá gì mà thiếu bạn.
- Delta prompt mang theo Code Map: những file thay đổi này chạm tới, kèm câu nói thẳng "file không có trong danh sách là không bị ảnh hưởng — đừng sửa".
- Agent viết thẳng thân usecase từ code nó vừa đọc — luật validate, input, các ca lỗi. Spec thôi là một danh sách tên.
- Không cần git. DSpecs không bao giờ nhìn thấy repo và không lưu commit id nào — nó tự theo dõi độ tươi của từng context, và chỉ yêu cầu agent quét lại phần đã cũ.
- Duyệt drift bằng một cú bấm: phần tử mới, dời chỗ và đổi tên áp theo lô. Phần tử vắng mặt không bao giờ bị xoá tự động — quét thiếu và bị xoá thật trông giống hệt nhau.
Agent quét repo — bạn duyệt
delta — code map
## 2. Code Map Modify only what section 1 requires; read the rest for context. Files not listed here are unaffected — do not modify them. - src/ordering/coupon.service.ts - src/ordering/order.entity.ts
Drift, xem lại rồi áp
2 new1 moved1 renamedApply 4 safe
Delta Update
Vòng lặp tiến lên.
Chỉ delta được gửi đi.
Sửa model và DSpecs bắt đúng phần khác biệt — rồi compile thành một prompt gọn: đã đổi gì, chạm file nào, và phần ngữ cảnh tối thiểu xung quanh. Không compile lại toàn bộ, không giải thích lại.
delta 740 token so với 8.2K bản đầy đủ — nhỏ hơn 91% (ví dụ minh hoạ)
Spec đầy đủ
~8.2K token
Delta Update
~740 token
DELTA-checkout-update.md — compiled by DSpecs
## 0. Constitution Stack: Next.js · Prisma · PostgreSQL ## 1. What Changed #### UPDATED Usecase: Checkout - contentText: "..." → "...award 1 point per $10" + CREATED Field: Customer.loyaltyPoints (int ≥ 0) ## 2. Relevant Context #### Entity: Customer ⭐ root #### Usecase: Award Loyalty Points · write ## 3. System Map - Ordering ← affected
Vòng lặp
Model → Compile → Build → Đồng bộ ngược
Model nằm ở trung tâm và vòng lặp khép kín cả hai chiều: bạn sửa specs, agent build, rồi agent đồng bộ code map ngược lại để model không bao giờ tụt hậu.
01
Mô hình & Map
Trỏ agent vào repo, nó map codebase thành context, entity, usecase — mỗi thứ gắn với file thật. Hoặc bắt đầu từ tài liệu, hoặc từ số không.
02
Compile & Constitution
Model cộng quy tắc dự án compile thành CLAUDE.md, AGENTS.md và Cursor rules — Constitution luôn render đầu tiên, nên một lát cắt mỏng cũng không mất quy ước của bạn.
03
Build
Agent kéo đúng thứ nó cần qua MCP: một usecase, một context, hoặc delta của bản update nó đang làm.
04
Đồng bộ ngược
Xong việc, agent hỏi DSpecs cần quét lại những gì — một work order tính từ thứ đã đổi trong model, không phải từ lịch sử git — rồi đẩy code map mới. Bạn xem drift và duyệt.
Constitution
Quy tắc của bạn đi kèm mọi prompt
Stack, kiến trúc, quy ước, ràng buộc bất di bất dịch — giữ dưới dạng thư viện các rule có tên thay vì một khối chữ, và chèn ở đầu mọi bản compile và mọi delta.
- Mỗi rule là một khối markdown có tên, sửa độc lập được.
- Đánh dấu default là rule tự đi kèm mọi bản compile.
- Chọn đúng những rule nào đi cùng bản compile đầy đủ hay delta.
- Luôn render đầu tiên, nên delta mỏng đến mấy cũng không mất quy ước.
- DSpecs seed sẵn một rule hệ thống dặn agent làm mới code map sau khi implement — tắt lúc nào cũng được.
constitution — rules library
✓ stack.md default · Next.js · Prisma · PostgreSQL ✓ conventions.md default · DDD, event-driven, i18n ○ legacy-api.md optional · pick per compile $ compile --delta ## 0. Project Constitution ### stack ### conventions ## 1. What Changed …