Adaptive AI Agent Protocol

Purpose

• Dùng một meta-prompt mềm để làm việc với AI agent khi idea còn thô, đa nghĩa, hoặc chưa rõ nên biến thành artifact nào.
• Giữ AI agent bám đúng ý định gốc trước khi ép idea thành wiki, spec, design-system rule, hay implementation plan.
• Thay template-first bằng intent-first.

Khi nào nên dùng

• Bạn đang có idea nhưng chưa chắc nên biến nó thành loại tài liệu nào.
• Mỗi lần làm việc có shape khác nhau nên form cố định gây méo ý.
• Bạn muốn AI agent khóa đúng ý định rồi mới cấu trúc dần.
• Một ý tưởng có thể rẽ sang nhiều lane như discovery, docs, wiki, design-system, hoặc planning.

Khi nào không cần dùng

• Bạn đã biết chính xác artifact cần tạo và format mong muốn.
• Bạn chỉ muốn AI agent thực hiện một tác vụ hẹp, rõ, và gần như không có ambiguity.
• Bạn đang ở pha review/fix kỹ thuật rất cụ thể, không cần thêm lớp intent lock.

Core principle

• Không hỏi: idea này thuộc template nào?
• Hỏi: AI agent phải hiểu và xử lý idea này như thế nào để không làm sai ý?

Operating model

1. Raw idea
   • Bạn đưa ý tưởng theo ngôn ngữ tự nhiên, chưa cần format.
2. Intent Lock
   • AI agent phản chiếu lại ý bạn, tách rõ fact, assumption, inference.
3. Adaptive shaping
   • AI agent chọn mức cấu trúc nhẹ nhất đang cần.
4. Artifact commitment
   • Chỉ khi intent đã đủ rõ, AI agent mới biến nó thành artifact phù hợp.

What the AI agent should do first

• Restate ý chính bằng ngôn ngữ ngắn, rõ, không generic.
• Nói agent tin rằng bạn thực sự muốn đạt điều gì.
• Chỉ ra assumption nào nó đang tự thêm vào.
• Nói artifact nào là phù hợp nhất ở bước hiện tại, nếu có.
• Không ép structure nếu idea vẫn còn nên ở trạng thái exploratory.

Recommended usage with AI agents

Sử dụng prompt nội bộ tại:

• .agent/prompts/adaptive-collaboration-protocol.md

Protocol này có thể dùng với:

• Codex
• Claude
• Anti-Gravity
• agent khác có lớp system hoặc developer prompt tương tự

Bạn có thể mở đầu một session bằng một câu ngắn như:

Use the adaptive collaboration protocol for this session.
Start with an Intent Lock before turning my idea into any artifact.

Sau đó đưa idea thô của bạn. Ví dụ:

Tôi đang nghĩ về một cách tổ chức lại knowledge flow giữa wiki, docs, và design system để AI không bị lệch context, nhưng tôi chưa biết là vấn đề này nên đi theo hướng rule, workflow, hay một artifact trung gian.

Minimal working loop

Loop A - khi idea còn mơ hồ

• Yêu cầu AI agent chỉ làm Intent Lock.
• Mục tiêu là kiểm tra nó đã hiểu đúng chưa, chưa vội chốt output.

Prompt gợi ý:

Use the adaptive collaboration protocol.
For now, do only an Intent Lock.
Do not turn this into a fixed template yet.

Loop B - khi idea đã có hướng

• Yêu cầu AI agent shape idea thành working brief.
• Chưa cần final artifact nếu vẫn còn ambiguity đáng kể.

Prompt gợi ý:

Use the adaptive collaboration protocol.
Do an Intent Lock, then shape this into a compact working brief.
Keep it flexible and do not over-structure it.

Loop C - khi bạn muốn chốt artifact

• Sau khi Intent Lock đúng, mới yêu cầu AI agent đổi sang artifact.

Prompt gợi ý:

Use the adaptive collaboration protocol.
Do an Intent Lock first.
If the intent is stable enough, turn it into the most suitable artifact and explain why that artifact fits.

Suggested artifact choices

• exploration note
  • khi idea còn mở và cần làm rõ đường đi
• working brief
  • khi đã có hướng nhưng chưa nên khóa thành spec
• spec / requirement framing
  • khi cần chốt decision, scope, acceptance, dependency
• wiki / documentation
  • khi điều cần làm là lưu tri thức hoặc tạo nguồn tham chiếu bền vững
• design-system rule / audit
  • khi ý tưởng thực chất là chuẩn hóa pattern, token, component, hoặc consistency rule
• implementation plan
  • khi ý đã đủ rõ để chuyển sang execution

Anti-patterns

• Đưa idea thô rồi yêu cầu AI agent viết full spec ngay từ đầu.
• Bắt AI agent dùng một form cố định cho mọi trường hợp.
• Để AI agent đổi ngôn ngữ của bạn thành generic PM prose mà không kiểm tra lại intent.
• Gộp ý bạn nói, giả định của agent, và khuyến nghị của agent vào cùng một lớp.

Expected output shape

Khi protocol đang hoạt động tốt, output đầu thường chỉ cần:

• Intent Lock
• Possible directions
• Recommended next step

Chỉ khi ý định đã đủ rõ mới nên yêu cầu:

• spec
• wiki draft
• design-system doc
• implementation plan

Why this fits multi-product work

• Cùng một idea có thể rẽ sang nhiều lane khác nhau.
• Protocol này không cố đoán lane quá sớm.
• Nó phù hợp với workspace có nhiều repo và nhiều loại artifact như:
  • EduDoc
  • Wiki
  • Design system
  • Playground planning

Maintenance note

• Prompt nội bộ là contract cho agent.
• Guide này là contract cho người dùng prompt.
• Nếu về sau thấy agent vẫn hay bị generic hóa, ưu tiên chỉnh file prompt trước, không mở rộng guide thành template mới.