Một kỹ sư giỏi có thể tự tối ưu prompt của mình xuống còn một nửa token trong một buổi chiều. Nhưng nếu 12 kỹ sư khác trong team vẫn đang viết prompt theo 12 cách khác nhau, tổ chức không tiết kiệm được gì đáng kể — chi phí token vẫn tăng đều theo số lượng người dùng agent, và không ai học được từ ai. Bài viết này đi vào phần khó hơn nhiều so với tối ưu cá nhân: biến kiến thức tối ưu token thành tài sản chung của cả team, thông qua thư viện prompt (prompt library) dùng chung, context template tiêu chuẩn hóa, quy trình review, và chuẩn mực riêng cho từng vai trò trong vòng đời phát triển phần mềm.

Vì Sao Tối Ưu Cá Nhân Là Chưa Đủ

Tối ưu token ở cấp cá nhân — rút ngắn một prompt, cắt bớt context dư thừa, chọn model rẻ hơn cho một tác vụ cụ thể — luôn là điểm khởi đầu tốt. Nhưng nó có ba giới hạn cấu trúc khiến nó không thể là chiến lược duy nhất của một tổ chức đang dùng AI agent ở quy mô nhiều team, nhiều dự án.

Thứ nhất, kiến thức không lan truyền tự nhiên. Một kỹ sư senior phát hiện ra rằng đưa toàn bộ file log 3.000 dòng vào prompt debug là lãng phí, và tự viết một script trích xuất 50 dòng liên quan nhất. Nếu không có cơ chế chia sẻ, phát hiện này chỉ nằm trong máy của người đó. Ba tháng sau, một kỹ sư khác trong cùng team lặp lại đúng sai lầm, đốt đúng số token tương tự, rồi tự mình phát hiện lại vấn đề — hoặc tệ hơn, không bao giờ phát hiện ra.

Thứ hai, chi phí biến động theo người, không theo tác vụ. Khi mỗi người tự viết prompt cho cùng một loại tác vụ (ví dụ: review pull request, phân tích lỗi test, viết user story), chi phí token cho "cùng một việc" có thể chênh nhau 3-5 lần giữa người tối ưu tốt và người chưa tối ưu. Với một team 20 người dùng AI agent hàng ngày, khoảng chênh này cộng lại thành hàng triệu token lãng phí mỗi tháng — một khoản chi phí ẩn mà không dashboard cá nhân nào cho thấy được, vì nó chỉ hiện ra khi so sánh chi phí giữa các thành viên.

Thứ ba, tối ưu cá nhân không có "bộ nhớ tổ chức" (organizational memory). Khi người tối ưu prompt tốt nhất nghỉ việc hoặc chuyển team, kiến thức đó biến mất theo họ. Không có prompt library, không có version control cho prompt, không có ai kế thừa được cách họ đã cấu trúc context để giảm 60% token cho một loại tác vụ cụ thể.

Giải pháp không phải là bắt mọi người tối ưu giỏi hơn — mà là biến những gì đã học được thành hạ tầng dùng chung: prompt library, context template, quy trình review, và chuẩn mực theo vai trò. Đây chính là bốn trụ cột của phần còn lại trong bài viết.

Mẹo: Trước khi đầu tư xây dựng bất kỳ hạ tầng nào ở dưới, hãy đo chi phí token theo từng loại tác vụ (không phải theo từng người) trong 2-4 tuần. Nếu bạn thấy độ lệch chuẩn giữa các lần thực thi cùng một loại tác vụ vượt quá 30-40%, đó là dấu hiệu rõ ràng rằng vấn đề nằm ở sự thiếu chuẩn hóa, không phải ở năng lực cá nhân — và đầu tư vào prompt library sẽ có ROI cao.

Xây Dựng Thư Viện Prompt Chung

Prompt library là một thư mục (thường nằm trong monorepo hoặc một repo riêng) chứa các prompt đã được kiểm chứng, đóng phiên bản (versioned), và có metadata mô tả rõ mục đích, chi phí token trung bình, và điều kiện sử dụng. Nó đóng vai trò tương đương với một thư viện component UI dùng chung — thay vì mỗi người viết lại button từ đầu, mọi người import từ một nguồn tin cậy.

Library Architecture

Cấu trúc thư mục nên phản ánh theo agent hoặc theo tác vụ, không theo người viết. Một cấu trúc phổ biến và dễ mở rộng:

prompts/
  agents/
    pr_review_agent/
      metadata.yaml
      system_prompt.md
      templates/
        review_summary.md
        inline_comment.md
      tests/
        golden_outputs.yaml
    bug_triage_agent/
      metadata.yaml
      system_prompt.md
      templates/
        triage_report.md
    test_generation_agent/
      metadata.yaml
      system_prompt.md
  shared/
    context_templates/
      jira_ticket.md
      code_file.md
      pr_diff.md
      test_failure.md
  scripts/
    lint_prompts.py
    validate_metadata.py
  CHANGELOG.md

Ba nguyên tắc thiết kế quan trọng:

1. Mỗi agent có một thư mục riêng, không gộp chung các prompt không liên quan vào một file lớn. Điều này giúp review theo diff dễ dàng và tránh xung đột merge khi nhiều người sửa cùng lúc.
2. Context template tách riêng khỏi prompt của agent, đặt trong shared/, vì nhiều agent khác nhau dùng chung một context template (ví dụ cả pr_review_agent và bug_triage_agent đều cần format code file).
3. Có tests/golden_outputs để mỗi khi sửa prompt, CI có thể kiểm tra output có còn đúng cấu trúc mong đợi không — tránh tình trạng "tối ưu token nhưng làm hỏng chất lượng output" mà không ai phát hiện kịp thời.

Repo này nên được version control bằng Git như bất kỳ code khác, với PR review bắt buộc cho mọi thay đổi prompt — chi tiết ở phần "Quy Trình Review Prompt" bên dưới.

Prompt Metadata Schema

Mỗi prompt cần một file metadata mô tả rõ ràng, máy đọc được, để công cụ linting và dashboard có thể tổng hợp chi phí, và để người dùng mới biết prompt này dùng khi nào, tốn bao nhiêu token.

name: pr_review_agent
version: 3.2.0
owner_team: platform-engineering
maintainers:
  - "@lan.nguyen"
  - "@minh.tran"
description: >
  Reviews a pull request diff and returns structured findings
  (bugs, style violations, missing tests). Used by the CI
  pipeline on every PR targeting main.
model: claude-sonnet-5
model_fallback: claude-haiku-4-5-20251001
avg_input_tokens: 1850
avg_output_tokens: 420
p95_input_tokens: 3200
cost_per_run_usd: 0.021
context_templates_used:
  - pr_diff
  - jira_ticket
max_diff_lines: 400        # trên ngưỡng này, phải dùng chunking
requires_full_file_context: false
last_reviewed: 2026-06-15
review_cadence_days: 90
changelog_ref: CHANGELOG.md#pr_review_agent
tags:
  - code-review
  - ci-integration
  - high-frequency   # gọi > 500 lần/ngày, ưu tiên tối ưu

Các trường quan trọng nhất khi tối ưu ở cấp team:

• avg_input_tokens / p95_input_tokens: cho biết prompt này "nặng" hay "nhẹ", giúp ưu tiên prompt nào cần tối ưu trước — thường bắt đầu từ những prompt có tags: high-frequency kết hợp p95_input_tokens cao.
• model_fallback: cho phép hệ thống tự động chuyển sang model rẻ hơn khi input dưới một ngưỡng độ phức tạp nhất định, một kỹ thuật đã đề cập ở các bài trước về routing theo độ phức tạp.
• review_cadence_days: bắt buộc mọi prompt phải được review lại theo lịch, tránh tình trạng prompt "mồ côi" không ai touch trong 2 năm dù model và best practice đã thay đổi nhiều lần.

Prompt Composition System

Khi số lượng agent tăng lên, việc mỗi agent tự ghép chuỗi (string concatenation) các đoạn prompt một cách tùy tiện dẫn đến trùng lặp và khó bảo trì. Một hệ thống composition đơn giản giúp lắp ráp prompt từ các block dùng chung — instructions cố định, context template, và input động — theo một quy tắc nhất quán, đồng thời tự động đo token trước khi gửi.

"""
Lightweight prompt composition system for the shared prompt library.
Loads a base system prompt + optional context templates, fills in
variables, and reports token estimates before the call is made.
"""

from pathlib import Path
from string import Template
import tiktoken
import yaml

LIBRARY_ROOT = Path(__file__).parent / "prompts"
SHARED_ROOT = LIBRARY_ROOT / "shared" / "context_templates"


class PromptComposer:
    def __init__(self, agent_name: str, encoding_name: str = "cl100k_base"):
        self.agent_dir = LIBRARY_ROOT / "agents" / agent_name
        self.metadata = self._load_metadata()
        self.encoder = tiktoken.get_encoding(encoding_name)

    def _load_metadata(self) -> dict:
        meta_path = self.agent_dir / "metadata.yaml"
        with open(meta_path, "r", encoding="utf-8") as f:
            return yaml.safe_load(f)

    def _load_context_template(self, template_name: str) -> str:
        path = SHARED_ROOT / f"{template_name}.md"
        return path.read_text(encoding="utf-8")

    def compose(self, variables: dict, context_templates: list[str] | None = None) -> str:
        system_prompt = (self.agent_dir / "system_prompt.md").read_text(encoding="utf-8")

        parts = [system_prompt]
        for tmpl_name in context_templates or self.metadata.get("context_templates_used", []):
            tmpl = self._load_context_template(tmpl_name)
            parts.append(Template(tmpl).safe_substitute(variables))

        composed = "\n\n---\n\n".join(parts)
        return composed

    def estimate_tokens(self, composed_prompt: str) -> int:
        return len(self.encoder.encode(composed_prompt))

    def check_budget(self, composed_prompt: str) -> dict:
        actual = self.estimate_tokens(composed_prompt)
        budget = self.metadata.get("p95_input_tokens", 4000)
        return {
            "actual_tokens": actual,
            "budget_tokens": budget,
            "over_budget": actual > budget,
            "overage_pct": round((actual / budget - 1) * 100, 1) if actual > budget else 0.0,
        }

Usage example:

from prompt_composer import PromptComposer

composer = PromptComposer(agent_name="pr_review_agent")

variables = {
    "PR_TITLE": "Fix race condition in payment webhook handler",
    "PR_DIFF": diff_text,          # đã được rút gọn bằng context template pr_diff
    "TICKET_SUMMARY": ticket_text, # đã qua context template jira_ticket
}

prompt = composer.compose(variables, context_templates=["pr_diff", "jira_ticket"])
budget_check = composer.check_budget(prompt)

if budget_check["over_budget"]:
    logger.warning(
        f"pr_review_agent prompt vượt budget {budget_check['overage_pct']}% "
        f"({budget_check['actual_tokens']} / {budget_check['budget_tokens']} tokens)"
    )

response = call_model(prompt, model=composer.metadata["model"])

Lợi ích thực tế của composer này là nó biến việc "đo token trước khi gọi model" từ một bước thủ công dễ bị quên, thành một bước tự động không thể bỏ qua — mọi agent dùng chung composer đều tự động có cảnh báo vượt budget, ghi log để dashboard cấp team tổng hợp.

Mẹo: Đừng bắt đầu bằng việc xây một hệ thống composition phức tạp. Bắt đầu với 2-3 agent có traffic cao nhất, di chuyển prompt của chúng vào cấu trúc thư mục chuẩn, rồi mới viết composer. Xây composer trước khi có nội dung để "compose" thường dẫn đến một abstraction sai, phải viết lại sau 2 tháng.

Context Templates cho Truyền Thông Tin Tiết Kiệm Token

Nếu prompt library giải quyết vấn đề "làm sao viết instructions một lần, dùng nhiều lần", thì context template giải quyết vấn đề song song: "làm sao đưa dữ liệu bên ngoài (ticket, code, diff, log lỗi) vào prompt mà không nhồi nhét toàn bộ nội dung thô". Đây thường là nguồn lãng phí token lớn nhất trong thực tế, lớn hơn cả phần instructions cố định.

The Context Template Design Principles

Nguyên tắc cốt lõi: một context template là một hàm biến đổi dữ liệu gốc (thường rất dài, chứa nhiều field không liên quan) thành một đoạn text ngắn, có cấu trúc, chỉ giữ lại thông tin mà agent thực sự cần cho tác vụ cụ thể đó. Ví dụ điển hình nhất là Jira ticket.

{
  "id": "PROJ-4821",
  "summary": "Payment webhook fails intermittently",
  "description": "...", 
  "comments": [ /* 34 comments, mostly status updates */ ],
  "attachments": [ /* 5 screenshots, log dumps */ ],
  "watchers": [ /* 12 users */ ],
  "custom_fields": { /* 18 fields, mostly unused */ },
  "history": [ /* full change log, 200+ entries */ ],
  "linked_issues": [ /* 6 tickets */ ]
}

## Ticket PROJ-4821: Payment webhook fails intermittently
Priority: High | Status: In Progress | Assignee: minh.tran

### Problem
Webhook handler occasionally times out under load (>50 req/s),
causing duplicate payment confirmations to be sent to customers.

### Latest relevant comment (2026-07-08, lan.nguyen)
Confirmed race condition in retry logic; lock is released
before the DB write completes.

### Acceptance criteria
- Webhook must be idempotent under concurrent retries
- No duplicate confirmation emails

Sự khác biệt ở đây không chỉ là "cắt ngắn" — nó là chọn lọc có chủ đích. Template giữ lại problem statement, comment mới nhất có liên quan, và acceptance criteria, còn bỏ toàn bộ watcher list, custom field không dùng, và lịch sử thay đổi trạng thái (vốn chỉ có ích cho báo cáo quản lý, không có ích cho agent đang review code). Kết quả thực tế đo được trên nhiều team: 200-450 token cho phiên bản template hóa, so với 2.000+ token cho JSON ticket đầy đủ — giảm 80-90% mà không mất thông tin cần thiết cho tác vụ.

Nguyên tắc áp dụng tương tự cho code file:

## File: src/payments/webhook_handler.py (lines 40-95, function process_webhook)
Language: Python | Last modified: 2026-07-01 by minh.tran

```python
def process_webhook(payload: dict, idempotency_key: str) -> WebhookResult:
    with acquire_lock(idempotency_key, ttl_seconds=30):
        if is_duplicate(idempotency_key):
            return WebhookResult.already_processed()
        result = confirm_payment(payload)
        record_idempotency_key(idempotency_key)
    return result

Related imports: acquire_lock from lib/locking.py, record_idempotency_key
writes to Redis with 24h TTL.

Thay vì gửi toàn bộ file 800 dòng, template chỉ gửi đúng hàm liên quan cùng vài dòng ngữ cảnh về import — đủ để agent hiểu logic mà không phải tải cả file. Tương tự với PR diff, vốn thường bị gửi thô kèm toàn bộ metadata Git không cần thiết:

PR #1847: Fix race condition in payment webhook handler

Base: main (a3f21c9) | Head: fix/webhook-race (e88b104) | +42 / -18 lines

Changed files (2)

src/payments/webhook_handler.py

-    if is_duplicate(idempotency_key):
-        return WebhookResult.already_processed()
+    with acquire_lock(idempotency_key, ttl_seconds=30):
+        if is_duplicate(idempotency_key):
+            return WebhookResult.already_processed()

tests/test_webhook_handler.py (+28 lines, new test cases only shown)

+def test_concurrent_webhook_calls_are_idempotent():
+    ...

Note: 3 unrelated formatting-only changes in this PR were omitted
from this context (see full diff link if needed).

Template này chủ động loại bỏ các thay đổi chỉ liên quan đến formatting (thường do auto-formatter tạo ra) và ghi rõ điều đó, để agent không tốn thời gian suy luận về những dòng không quan trọng, đồng thời không đánh mất khả năng truy xuất nếu cần xem đầy đủ.

### Shared Context Template Library

Khi một team đã có 4-5 context template hữu ích, bước tiếp theo là biến chúng thành thư viện dùng chung thay vì để mỗi agent tự định nghĩa lại. Thư viện này nên có:

- **Một naming convention rõ ràng**: `jira_ticket.md`, `code_file.md`, `pr_diff.md`, `test_failure.md`, `sprint_backlog.md` — tên phản ánh loại dữ liệu nguồn, không phải agent nào dùng.
- **Biến đầu vào (input variables) được document rõ**, thường ở đầu file dưới dạng comment, để người viết agent mới biết cần truyền field nào.
- **Một bộ test đo token thực tế** cho vài input mẫu (nhỏ, trung bình, lớn) để phát hiện sớm khi template "phình" trở lại theo thời gian — điều này rất dễ xảy ra khi ai đó thêm một field "tạm thời" rồi quên xóa.
- **Một changelog** ghi lại lý do mỗi lần sửa — ví dụ "bỏ trường watchers vì không agent nào dùng đến, giảm ~150 token/ticket".

Một ma trận nhỏ ánh xạ agent nào dùng template nào giúp việc thay đổi một template không vô tình phá vỡ agent khác — đây chính là lý do file `metadata.yaml` ở trên có trường `context_templates_used`.

**Mẹo:** Khi viết context template mới, luôn viết trước phiên bản "toàn bộ dữ liệu thô" và đo token của nó, ghi số này vào docstring hoặc comment đầu file template (như ví dụ "Typical: 200-450 tokens vs 2,000+ for full ticket" ở trên). Con số before/after này là bằng chứng thuyết phục nhất khi bạn cần giải trình lý do tồn tại của template với người review không quen thuộc với tối ưu token.

## Xây Dựng Thực Hành Tối Ưu Token Ở Cấp Team

Có thư viện và template là điều kiện cần, nhưng chưa đủ — nếu không có quy trình bắt buộc sử dụng và duy trì chất lượng, thư viện sẽ dần lỗi thời trong khi mọi người quay lại viết prompt tùy ý. Ba cơ chế dưới đây — review, linting, và stand-up — biến việc tối ưu token từ một hoạt động "khi có thời gian" thành một phần bình thường của quy trình phát triển, giống như code review hay CI vậy.

### Quy Trình Review Prompt

Mọi thay đổi vào prompt library nên đi qua pull request, giống code thông thường, với một checklist rõ ràng cho cả người submit và người approve.

Prompt Change Review Checklist

Before Submitting a Prompt PR

• [ ] Đã chạy scripts/lint_prompts.py cục bộ, không còn warning nào
• [ ] Đã đo token trước/sau bằng PromptComposer.estimate_tokens(),
  ghi số liệu vào phần mô tả PR
• [ ] Đã chạy golden_outputs.yaml, output vẫn đạt chất lượng tương đương
  hoặc tốt hơn (không chỉ ngắn hơn)
• [ ] Đã cập nhật metadata.yaml nếu avg_input_tokens thay đổi > 10%
• [ ] Đã cập nhật CHANGELOG.md với lý do thay đổi

Review Criteria for Approvers

• [ ] Prompt có còn dễ đọc, dễ maintain không, hay đã bị "nén" đến mức
  chỉ tác giả hiểu được?
• [ ] Nếu prompt dùng context template mới, template đó đã tồn tại
  trong shared/context_templates chưa? Nếu chưa, có nên thêm không
  thay vì viết logic riêng?
• [ ] Số liệu token before/after có hợp lý so với nội dung thay đổi
  không (ví dụ: giảm 40% token nhưng không giải thích được là dấu
  hiệu cảnh báo, không phải thành tích)?
• [ ] Thay đổi này có breaking change nào với agent khác đang dùng
  chung context template này không?

Điểm quan trọng nhất trong checklist review là mục cuối của phần approver: một con số giảm token ấn tượng mà không có lời giải thích hợp lý thường là dấu hiệu prompt đã bị cắt quá tay, mất thông tin cần thiết — điều này chỉ lộ ra vài tuần sau khi chất lượng output âm thầm giảm.

### Prompt Linting Trong CI

Giống như linter cho code, một linter cho prompt tự động bắt các lỗi phổ biến trước khi merge — không cần con người nhớ kiểm tra thủ công mỗi lần.

```python
"""
CI linter for the shared prompt library. Fails the build if a prompt
change violates token-efficiency or structural rules.

Usage: python scripts/lint_prompts.py --path prompts/agents/
"""

import re
import sys
import yaml
import argparse
from pathlib import Path

MAX_SYSTEM_PROMPT_TOKENS = 1200
FORBIDDEN_PATTERNS = [
    (r"(?i)please\s+(kindly\s+)?note that", "Cụm từ dư thừa, không cần thiết cho model"),
    (r"(?i)as an ai", "Không cần meta-comment về bản chất model"),
    (r"\{\{.*full_object.*\}\}", "Có vẻ đang truyền toàn bộ object thô, hãy dùng context template"),
]


def rough_token_estimate(text: str) -> int:
    # Ước lượng nhanh: ~4 ký tự/token cho tiếng Anh, dùng khi chưa gọi API đo thật
    return len(text) // 4


def lint_metadata(agent_dir: Path) -> list[str]:
    errors = []
    meta_path = agent_dir / "metadata.yaml"
    if not meta_path.exists():
        return [f"{agent_dir.name}: thiếu metadata.yaml"]

    meta = yaml.safe_load(meta_path.read_text(encoding="utf-8"))
    required_fields = ["name", "owner_team", "avg_input_tokens", "model"]
    for field in required_fields:
        if field not in meta:
            errors.append(f"{agent_dir.name}: metadata.yaml thiếu field '{field}'")
    return errors


def lint_system_prompt(agent_dir: Path) -> list[str]:
    errors = []
    prompt_path = agent_dir / "system_prompt.md"
    if not prompt_path.exists():
        return [f"{agent_dir.name}: thiếu system_prompt.md"]

    text = prompt_path.read_text(encoding="utf-8")
    estimated = rough_token_estimate(text)
    if estimated > MAX_SYSTEM_PROMPT_TOKENS:
        errors.append(
            f"{agent_dir.name}: system_prompt.md ước tính {estimated} tokens, "
            f"vượt ngưỡng {MAX_SYSTEM_PROMPT_TOKENS}"
        )

    for pattern, reason in FORBIDDEN_PATTERNS:
        if re.search(pattern, text):
            errors.append(f"{agent_dir.name}: pattern '{pattern}' bị chặn — {reason}")

    return errors


def main():
    parser = argparse.ArgumentParser()
    parser.add_argument("--path", default="prompts/agents/")
    args = parser.parse_args()

    all_errors = []
    for agent_dir in sorted(Path(args.path).iterdir()):
        if not agent_dir.is_dir():
            continue
        all_errors.extend(lint_metadata(agent_dir))
        all_errors.extend(lint_system_prompt(agent_dir))

    if all_errors:
        print("Prompt lint FAILED:\n")
        for err in all_errors:
            print(f"  - {err}")
        sys.exit(1)

    print(f"Prompt lint passed for all agents under {args.path}")
    sys.exit(0)


if __name__ == "__main__":
    main()

Chạy script này trong CI (ví dụ như một job GitHub Actions kích hoạt trên mọi PR đổi file dưới prompts/) đảm bảo không ai vô tình merge một system prompt phình to 3.000 token, hoặc quên field bắt buộc trong metadata. FORBIDDEN_PATTERNS nên được team tự bổ sung dần theo các lỗi thực tế đã gặp — đây là nơi kinh nghiệm tối ưu của team được mã hóa thành quy tắc tự động, thay vì nằm trong đầu một vài người.

Định Dạng Stand-Up Tối Ưu Token Hàng Tuần

Ngoài quy trình PR, một buổi trao đổi ngắn hàng tuần giúp duy trì văn hóa quan sát và cải tiến liên tục, tương tự stand-up của Scrum nhưng tập trung riêng vào chi phí và hiệu quả token.

## Weekly Token Optimization Check-In (15 min)

**Trước buổi họp** — mỗi người mang theo:
- 1 số liệu: agent/prompt nào tốn token nhiều nhất trong tuần (từ dashboard)
- 1 phát hiện: một pattern lãng phí mới quan sát được (nếu có)

**Agenda (15 phút, không quá giờ):**
1. (5 phút) Xem dashboard chi phí token tuần này so với tuần trước —
   agent nào tăng bất thường? Có PR nào mới merge gây ra không?
2. (5 phút) Mỗi người chia sẻ 1 phát hiện — pattern lãng phí, prompt
   trùng lặp phát hiện được, hoặc một context template cần bổ sung
3. (5 phút) Chốt action item: ai sẽ mở PR sửa gì, deadline khi nào,
   ghi vào backlog `prompts/BACKLOG.md`

**Không làm trong buổi này:**
- Không debug prompt cụ thể tại chỗ (đưa vào PR review riêng)
- Không thảo luận chọn model cho tác vụ mới (đưa vào kênh riêng)

Buổi họp này chỉ hiệu quả nếu có dashboard chi phí cập nhật (xem bài trước về đo lường và giám sát) làm nền tảng dữ liệu — nếu không có số liệu cụ thể, buổi họp dễ biến thành than phiền chung chung không dẫn đến hành động cụ thể.

Mẹo: Giới hạn cứng 15 phút là chủ đích, không phải gợi ý. Một buổi họp tối ưu token kéo dài 45 phút thường có nghĩa là bạn đang debug một prompt cụ thể trong cuộc họp — hãy tách việc đó ra thành một PR review riêng, và giữ stand-up làm nơi phát hiện vấn đề, không phải nơi giải quyết vấn đề.

Chuẩn Tối Ưu Theo Từng Persona

Kỹ sư, QA, và product manager tương tác với AI agent theo những cách khác nhau, với dữ liệu đầu vào và mục tiêu khác nhau — vì vậy chuẩn tối ưu token dùng chung cho cả ba nhóm thường quá chung để hữu ích. Phần này đưa ra chuẩn cụ thể cho mỗi vai trò.

Dành Cho Software Engineers

## Engineering Prompt Standards

### Tool Definitions
- Chỉ đăng ký (register) tool mà agent thực sự cần cho tác vụ hiện tại,
  không load toàn bộ bộ tool có sẵn trong hệ thống "cho chắc"
- Mỗi tool definition không vượt 80 token mô tả — nếu cần giải thích
  dài hơn, đó là dấu hiệu tool đang làm quá nhiều việc, nên tách nhỏ
- Tên tham số (parameter) phải tự giải thích được, tránh phải viết
  thêm câu mô tả dài trong docstring của tool

### Code Context
- Dùng context template `code_file` (mục trên) thay vì paste nguyên
  file — chỉ gửi hàm/class liên quan cùng signature của các dependency
- Với review PR, dùng context template `pr_diff`, loại bỏ các thay đổi
  formatting-only trước khi gửi vào agent
- Với debug, ưu tiên gửi stack trace + 10-15 dòng quanh điểm lỗi, thay
  vì gửi toàn bộ file log

### Conversation Management
- Đóng (close) conversation sau khi hoàn thành tác vụ, không giữ một
  session kéo dài nhiều ngày cho nhiều tác vụ không liên quan — history
  cũ tích tụ làm tăng token mỗi lượt gọi tiếp theo
- Với tác vụ nhiều bước, tóm tắt lại trạng thái hiện tại thành 3-5 dòng
  trước khi tiếp tục, thay vì để agent tự đọc lại toàn bộ lịch sử

Dành Cho QA Engineers

## QA Prompt Standards

### Test Failure Analysis
- Gửi kèm context template `test_failure`: chỉ tên test, assertion
  thất bại, giá trị expected/actual, và 5-10 dòng log ngay trước lỗi —
  không gửi toàn bộ log CI (thường vài nghìn dòng)
- Nếu lỗi lặp lại (flaky test), gửi kèm tỷ lệ fail trong 20 lần chạy
  gần nhất thay vì gửi log của cả 20 lần chạy đó

### Test Generation
- Khi yêu cầu agent viết test mới, chỉ cung cấp signature của hàm cần
  test + 1-2 test case hiện có làm ví dụ style, không cung cấp toàn bộ
  file test hiện tại
- Yêu cầu rõ số lượng test case mong muốn (ví dụ "viết 4 test case:
  happy path, empty input, boundary value, concurrent access") để agent
  không tự sinh ra 15 test case dư thừa, tốn token output không cần thiết

### Bug Triage
- Dùng context template `jira_ticket` đã lược bớt (mục trên) khi yêu
  cầu agent phân loại độ nghiêm trọng hoặc gợi ý assignee
- Với bug liên quan đến nhiều ticket, chỉ gửi tiêu đề + trạng thái của
  các ticket liên quan, không gửi toàn bộ nội dung từng ticket

Dành Cho Product Managers

## Product Management Prompt Standards

### User Story Generation
- Cung cấp template cố định cho agent điền vào (As a / I want / So that
  + acceptance criteria) thay vì để agent tự do viết văn xuôi dài rồi
  phải parse lại — output có cấu trúc giúp cả input yêu cầu ít token
  hơn và output dễ dùng ngay
- Giới hạn số lượng acceptance criteria mong muốn (ví dụ "3-5 tiêu chí")
  trong prompt để tránh output lan man

### Sprint Planning
- Khi yêu cầu agent ước lượng effort hoặc sắp xếp backlog, gửi kèm
  danh sách ticket dạng rút gọn (tiêu đề + story point cũ + priority),
  không gửi mô tả đầy đủ của từng ticket — agent chỉ cần đủ để so sánh
  tương đối, không cần đọc lại toàn bộ ngữ cảnh nghiệp vụ mỗi ticket
- Tách riêng prompt "ước lượng effort" và prompt "sắp xếp thứ tự" —
  gộp hai việc vào một prompt dài thường ra kết quả kém hơn cả hai
  prompt ngắn, chuyên biệt

### Document Analysis
- Khi yêu cầu agent tóm tắt tài liệu yêu cầu (PRD, spec) dài, chia nhỏ
  theo section và tóm tắt từng phần trước, rồi tổng hợp — tránh nhồi
  toàn bộ tài liệu 20 trang vào một lần gọi duy nhất
- Với tài liệu có phần "Background"/"Context" lịch sử dài dòng, có thể
  bỏ qua phần này khi hỏi agent về scope hiện tại, chỉ gửi phần
  "Requirements" và "Out of scope"

Mẹo: Đừng viết chuẩn persona này một lần rồi để yên. Sau mỗi buổi stand-up tối ưu token hàng tuần (mục trên), nếu một phát hiện áp dụng riêng cho một vai trò cụ thể, hãy cập nhật ngay vào phần persona tương ứng — các chuẩn này có giá trị nhất khi phản ánh vấn đề thật của chính team, không phải danh sách lý thuyết chung.

Đo Lường Thành Công Của Tối Ưu Cấp Team

Đầu tư vào prompt library, context template, và quy trình review chỉ có ý nghĩa nếu bạn đo được tác động. Bốn nhóm chỉ số nên theo dõi ở cấp team, tách biệt với chỉ số cấp cá nhân đã nói ở các bài trước:

• Tỷ lệ sử dụng thư viện chung (adoption rate): bao nhiêu phần trăm agent trong hệ thống đang dùng prompt/context template từ thư viện chung, so với prompt viết tay không qua review. Một team mới bắt đầu thường ở mức 20-30%; mục tiêu hợp lý sau 2-3 tháng là trên 80%.
• Độ lệch chuẩn chi phí token theo loại tác vụ: đo phương sai giữa các lần thực thi cùng một loại tác vụ (review PR, phân tích test fail, v.v.). Độ lệch chuẩn giảm dần theo thời gian là dấu hiệu chuẩn hóa đang phát huy hiệu quả — thay vì chi phí phụ thuộc vào ai gọi agent, nó phụ thuộc vào độ phức tạp thực của tác vụ.
• Thời gian trung bình để onboard một agent/prompt mới: từ lúc bắt đầu viết đến lúc merge qua review, đạt chuẩn linting. Thư viện tốt giúp số này giảm dần vì người viết mới tái sử dụng context template có sẵn thay vì viết từ đầu.
• Tổng token/tháng trên mỗi loại tác vụ, quy theo số lần thực thi: chỉ số tổng hợp cuối cùng, nên vẽ theo tháng để thấy xu hướng dài hạn, tách theo agent để biết đầu tư tối ưu tiếp theo nên nhắm vào đâu.

Một cách trình bày hữu ích là dashboard so sánh "trước và sau khi có prompt library" cho 2-3 agent có traffic cao nhất — đây là bằng chứng cụ thể nhất để thuyết phục các team khác tham gia, và để biện minh cho thời gian đầu tư duy trì thư viện với các bên liên quan không trực tiếp viết prompt.

Mẹo: Đừng chỉ báo cáo tổng token tiết kiệm được bằng USD — con số đó dễ bị coi là "chi phí nhỏ, không đáng ưu tiên" khi so với ngân sách kỹ thuật tổng thể. Thay vào đó, gắn số liệu tối ưu token với chỉ số mà lãnh đạo quan tâm hơn: thời gian phản hồi của agent (token ít hơn thường đồng nghĩa latency thấp hơn), và khả năng mở rộng số lượng tác vụ agent xử lý được trong cùng ngân sách hạ tầng.

Tổng Kết

Tối ưu token ở cấp cá nhân là điểm khởi đầu cần thiết nhưng không đủ cho một tổ chức dùng AI agent ở quy mô nhiều người, nhiều team. Giá trị thực sự đến từ việc biến kiến thức tối ưu thành hạ tầng dùng chung: một prompt library có cấu trúc rõ ràng theo agent, kèm metadata schema đủ thông tin để đo lường và ưu tiên; một hệ thống composition tách biệt instructions cố định khỏi context động; và một thư viện context template chuẩn hóa cách đưa dữ liệu (ticket, code, diff, log lỗi) vào prompt mà không nhồi nhét dữ liệu thô — thường tiết kiệm 80-90% token so với cách làm ngây thơ.

Ba cơ chế duy trì — quy trình review prompt với checklist rõ ràng cho cả người submit và approver, linting tự động trong CI để bắt lỗi trước khi merge, và stand-up hàng tuần 15 phút tập trung vào dữ liệu thật — giữ cho thư viện này sống và cải tiến liên tục, thay vì lỗi thời sau vài tháng. Cuối cùng, chuẩn tối ưu riêng cho kỹ sư, QA, và product manager thừa nhận rằng ba vai trò này tương tác với agent theo cách khác nhau, và cần hướng dẫn cụ thể, không phải nguyên tắc chung mơ hồ.

Đo lường thành công không chỉ bằng USD tiết kiệm được, mà bằng tỷ lệ sử dụng thư viện chung, độ lệch chuẩn chi phí giữa các lần thực thi cùng tác vụ, và tốc độ onboard prompt mới — những chỉ số phản ánh đúng bản chất của tối ưu cấp team: biến chi phí token từ một biến số ngẫu nhiên phụ thuộc vào từng cá nhân, thành một tài sản kỹ thuật được quản lý, đo lường, và cải tiến có chủ đích.