Chọn context khi nhờ AI sửa code có sẵn

Câu hỏi bài này trả lời: khi nhờ AI agent sửa một lỗi trong codebase đã có, nên đưa vào những gì và bỏ những gì để nó sửa đúng chỗ, và bạn kiểm được kết quả?

Cần biết trước: đọc được code Python cơ bản; biết agent đọc được file trong repo hoặc nhận nội dung bạn dán vào. Muốn phân biệt prompt, skill, quy tắc dự án và tool thì xem AI Agent Skills. Phần lab cần Python 3.10 trở lên, không cài thêm thư viện.

Lời nhờ “API checkout bị timeout, sửa giúp” thiếu gần hết thứ cần để chọn bản sửa đúng. Dán cả repo và toàn bộ log cũng không giúp được: khối lượng không phải là thông tin. Bài này dùng một lỗi giả lập để chỉ ra bộ input nhỏ nhưng đủ, lý do từng mảnh có mặt trong đó và cách kiểm kết quả bằng test.

Tình huống

Dịch vụ shop có endpoint POST /checkout. Handler gọi lần lượt hai dịch vụ ngoài: kho (giữ hàng) và carrier (báo phí vận chuyển). Sau một lần refactor, người dùng báo checkout bị treo; gateway cắt ở 10 giây và trả 504. Cây mã của lab:

shop/
├── config.py
├── errors.py
├── api/
│   ├── checkout.py
│   └── steps.py
└── clients/
    ├── http_json.py
    ├── inventory.py
    └── shipping.py
tests/
└── test_checkout.py

Lab thu nhỏ thang thời gian: carrier trả lời sau 1,5 giây thay vì 30 giây, và ngân sách cho mỗi lời gọi ngoài là 0,5 giây. Hành vi giống nhau ở hai thang, chỉ con số khác.

• Mong đợi: carrier không trả lời trong 0,5 giây thì checkout trả 503 kèm {"error": "upstream_timeout", "service": "shipping"} ngay sau đó.
• Thực tế: checkout chờ đến khi carrier trả lời rồi mới trả 200. Trong sự cố thật carrier không trả lời, nên request treo đến lúc gateway cắt.
• Phạm vi cần sửa: một file, shop/clients/shipping.py.

Ba cách đưa input

Thiếu

API checkout bị timeout, sửa giúp.

Từ câu này chưa quyết được:

• “Timeout” xảy ra ở đâu (gateway, handler hay một lời gọi ngoài), và mong đợi là báo lỗi hay trả kết quả dự phòng?
• Sửa ở đâu: handler, client của carrier, helper HTTP dùng chung hay cấu hình gateway?
• Bao lâu thì chấp nhận được, và làm sao biết đã sửa xong?

Mỗi câu hỏi có ít nhất hai đáp án hợp lý. Bản sửa nào cũng có thể “trông chạy được” mà không có tiêu chí nào để kiểm.

Thừa

Dán toàn bộ mã nguồn, toàn bộ log và thêm câu “sửa timeout giúp”. Lab nhỏ này đã là 144 dòng, gồm 136 dòng code và 8 dòng log (số đếm ở phần lab bên dưới); riêng file test chiếm 63 dòng. Ở repo thật con số lớn hơn nhiều bậc. Kích thước chưa phải vấn đề chính: bộ này vẫn thiếu những mảnh quan trọng nhất. Không chỗ nào nói mong đợi là gì, không có diff cho thấy thay đổi nào gây lỗi, và phạm vi sửa để mở, kể cả helper http_json.py mà mọi client dùng chung.

Đủ

Bộ đủ có tám mảnh. Mỗi mảnh đi cùng một câu hỏi: nếu bỏ mảnh này thì quyết định nào không còn căn cứ?

Tám mảnh của bộ input đủ

1. Mục tiêu và hành vi mong đợi

Mục tiêu: sửa lỗi POST /checkout bị treo khi carrier phản hồi chậm.

Mong đợi: nếu carrier không trả lời trong SHIPPING_TIMEOUT (0,5 giây), checkout
trả 503 với {"error": "upstream_timeout", "service": "shipping"} ngay sau đó.
Thực tế: checkout chờ đến khi carrier trả lời rồi mới trả 200. Người dùng báo
gateway cắt ở 10 giây và trả 504.

Mảnh này chốt hợp đồng: trả lỗi 503 chứ không trả kết quả dự phòng, và hạn là SHIPPING_TIMEOUT. Thiếu nó, “sửa timeout” có ít nhất hai cách hiểu với hai hợp đồng API khác nhau, và không viết được test.

2. Phạm vi

Được sửa: shop/clients/shipping.py, và thêm test nếu cần.
Không đổi: chữ ký get_json(), shop/config.py, cách checkout.py ánh xạ lỗi
sang HTTP, dependency.

Mảnh này đóng vùng ảnh hưởng. get_json được mọi client dùng chung: một bản sửa “tiện tay” ở đó đổi hành vi của cả hệ thống, và người đọc diff khó nhận ra.

3. Bằng chứng: test lỗi và log đã lọc

Cả hai là kết quả của một lần chạy, không nằm trong repo, nên phải dán. Test thất bại cho biết hợp đồng bị vi phạm thế nào:

FAIL: test_slow_carrier_returns_503_within_budget (test_checkout.CheckoutTest.test_slow_carrier_returns_503_within_budget)
AssertionError: 1.5 not less than 1.0
Ran 2 tests in 3.514s
FAILED (failures=1)

Phần trong ngoặc của dòng FAIL: khác nhau giữa các phiên bản Python, và thời gian khác nhau theo máy. Log thô chứa nhiều request; lọc theo request id trước khi dán:

grep "rid=slow-1" app.log

rid=slow-1 step=inventory.reserve start
rid=slow-1 step=inventory.reserve ok elapsed=0.00s
rid=slow-1 step=shipping.quote start
rid=slow-1 step=shipping.quote ok elapsed=1.50s

Đọc log: kho trả lời tức thì (0.00s), thời gian nằm hết ở shipping.quote (1.50s, so với ngân sách 0,5 giây). Trong sự cố thật dòng ok cuối không bao giờ xuất hiện. Ẩn dữ liệu cá nhân, token và khóa trước khi dán log vào bất kỳ công cụ nào.

4. Code đang lỗi

File chứa lời gọi lỗi. Chỉ 7 dòng nên dán cả file; ở repo thật chỉ dán hàm liên quan hoặc trỏ đường dẫn. Điều cần thấy: get_json(url) được gọi không có timeout.

from shop import config
from shop.clients.http_json import get_json


def shipping_quote(zip_code):
    url = f"{config.SHIPPING_URL}/quote?zip={zip_code}"
    return get_json(url)

5. Nơi lỗi được ánh xạ sang HTTP

Handler bắt UpstreamTimeout và đổi thành 503. Điều này ràng buộc bản sửa: lỗi của carrier phải là UpstreamTimeout("shipping"), không phải một exception mới hay TimeoutError trần mà handler không bắt. Đây là hợp đồng chứ không phải chỗ cần sửa, nên mảnh 2 cấm đổi file này.

from shop.api.steps import timed
from shop.clients.inventory import reserve
from shop.clients.shipping import shipping_quote
from shop.errors import UpstreamTimeout


def checkout(order):
    rid = order["rid"]
    try:
        timed(rid, "inventory.reserve", reserve, order["sku"], order["qty"])
        quote = timed(rid, "shipping.quote", shipping_quote, order["zip"])
    except UpstreamTimeout as exc:
        return 503, {"error": "upstream_timeout", "service": exc.service}
    return 200, {"shipping": quote}

6. Thay đổi gần nhất chạm vào chỗ nghi ngờ

Diff của lần refactor gần nhất (giả lập) cho thấy lời gọi trực tiếp được thay bằng get_json(url), kéo theo mất hai thứ: timeout= và bước đổi TimeoutError thành UpstreamTimeout.

--- a/shop/clients/shipping.py
+++ b/shop/clients/shipping.py
@@ -1,14 +1,7 @@
-import json
-import urllib.request
-
 from shop import config
-from shop.errors import UpstreamTimeout
+from shop.clients.http_json import get_json


 def shipping_quote(zip_code):
     url = f"{config.SHIPPING_URL}/quote?zip={zip_code}"
-    try:
-        with urllib.request.urlopen(url, timeout=config.SHIPPING_TIMEOUT) as response:
-            return json.load(response)
-    except TimeoutError as exc:
-        raise UpstreamTimeout("shipping") from exc
+    return get_json(url)

Đưa nó như giả thuyết cần kiểm, không phải kết luận: test lỗi vẫn là phán quyết cuối cùng. Thiếu mảnh này, người sửa phải tự lần lịch sử thay đổi hoặc đoán nguyên nhân từ triệu chứng.

7. Ví dụ cùng quy ước

Một đoạn đã đúng trong cùng repo cho thấy quy ước: truyền timeout=config.<DỊCH_VỤ>_TIMEOUT, bắt TimeoutError, ném UpstreamTimeout("<dịch vụ>") from exc. Mô tả bằng lời (“thêm timeout và xử lý lỗi như kho”) bỏ ngỏ kiểu exception, tên hằng số và cách bọc lỗi; đoạn code thì không.

from shop import config
from shop.clients.http_json import get_json
from shop.errors import UpstreamTimeout


def reserve(sku, qty):
    url = f"{config.INVENTORY_URL}/reserve?sku={sku}&qty={qty}"
    try:
        return get_json(url, timeout=config.INVENTORY_TIMEOUT)
    except TimeoutError as exc:
        raise UpstreamTimeout("inventory") from exc

8. Cách kiểm

Chạy: python3 -m unittest discover -s tests
Đạt khi: test_healthy_carrier_returns_200 và
test_slow_carrier_returns_503_within_budget cùng pass, và chỉ
shop/clients/shipping.py thay đổi.
Nếu không chạy được lệnh, nói rõ phần chưa kiểm; không báo đã sửa xong
khi chưa có kết quả test.

Mảnh này cho điều kiện dừng đo được và cách báo cáo khi không kiểm được. Thiếu nó, “đã sửa xong” chỉ là lời tự báo cáo.

Vì sao bỏ timeout lại thành treo

Ba mảnh cùng chỉ về một nguyên nhân: diff cho thấy refactor bỏ timeout=, ví dụ cho thấy cách đúng, log cho thấy thời gian nằm ở bước shipping.quote.

Cơ chế nằm ở chỗ thư viện chuẩn không đặt giới hạn thời gian nào theo mặc định. Tài liệu urllib.request.urlopen nói nếu không chỉ định timeout thì dùng timeout mặc định toàn cục, và socket.getdefaulttimeout() trả về None khi module được import lần đầu, nghĩa là socket mới không có timeout. Helper get_json(url, timeout=None) cũng không đặt giới hạn: khi nơi gọi quên truyền timeout, lời gọi chờ cho đến khi phía kia trả lời hoặc đóng kết nối. Vì vậy một refactor chỉ gom code có thể đổi hành vi mà không gây lỗi cú pháp; thường chỉ một test về thời hạn mới bắt được.

Mẫu prompt dùng lại

Dán các mảnh theo thứ tự trên vào cùng một tin nhắn, mỗi mảnh dưới một tiêu đề. Khung dưới đây dùng lại được cho lỗi khác:

Mục tiêu: <một câu: lỗi gì, ở đâu>

Mong đợi: <kết quả quan sát được, có số hoặc điều kiện>
Thực tế: <điều đang xảy ra>

Phạm vi
- Được sửa: <file hoặc hàm>
- Không đổi: <API công khai, cấu hình, thư viện dùng chung, dependency>

Bằng chứng
<output test lỗi; log đã lọc theo request hoặc khung giờ>

Code liên quan
<file hoặc hàm trực tiếp tham gia lỗi: dán hoặc trỏ đường dẫn>

Thay đổi gần nhất (giả thuyết, chưa kiểm)
<diff hoặc commit nghi ngờ>

Ví dụ cùng quy ước
<một đoạn đã đúng trong cùng repo>

Cách kiểm
<lệnh chạy và điều kiện đạt; nếu không chạy được thì nêu phần chưa kiểm>

Checklist trước khi gửi:

• Mỗi mảnh trả lời được: “bỏ mảnh này thì quyết định nào mất căn cứ?”
• Có mong đợi và thực tế đo được (con số, mã trạng thái, tên test)?
• Phạm vi nêu cả phần được sửa lẫn phần không đổi?
• Log lọc theo request hoặc khung giờ, đã ẩn dữ liệu cá nhân, token và khóa?
• Bằng chứng khớp đúng phiên bản code đang lỗi?
• Ví dụ cùng quy ước thật sự đúng (có test hoặc đang chạy ổn định)?
• Có lệnh kiểm và điều kiện đạt; agent biết phải báo gì nếu không chạy được?
• Không có file hay đoạn log nào chỉ để “cho chắc”?

Vì sao chọn như vậy

Mỗi mảnh gắn với một quyết định

Cột cuối theo hướng agent nạp context theo nhu cầu: giữ đường dẫn nhẹ và chỉ đọc file khi cần, thay vì nạp trước mọi thứ (Anthropic). Đây là khuyến nghị thực hành, không phải quy luật. Dán những gì agent không tự lấy được; trỏ những gì nằm trong repo nó đọc được. Với chat không truy cập repo thì dán cả code. Best practices của Claude Code khuyến nghị cùng hướng khi giao việc sửa lỗi: nêu triệu chứng, vị trí khả nghi và “sửa xong” trông thế nào, và chỉ tới mẫu có sẵn trong codebase.

Bốn tiêu chí chọn context

Bốn nhãn này là cách gọi trong wiki này, không phải thuật ngữ chuẩn của ngành.

Độ dài context: nguồn nói gì và chưa nói gì

Nhồi thêm context không phải lúc nào cũng vô hại. Ba nguồn dưới đây mô tả điều đó, kèm những giới hạn đáng đọc kỹ:

• Anthropic (2025-09-29) coi context là tài nguyên hữu hạn, gọi hiện tượng độ chính xác khi nhớ thông tin giảm theo số token là “context rot”, và đặt mục tiêu là tập token nhỏ nhất nhưng nhiều tín hiệu nhất. Họ lý giải bằng “attention budget” và việc n token tạo n² quan hệ từng cặp; đó là lời giải thích của tác giả bài viết, không phải kết quả đo. Họ cũng nhấn mạnh đây là độ dốc dần chứ không phải vách đứng: model vẫn mạnh ở context dài nhưng độ chính xác có thể giảm.
• Liu và cộng sự, “Lost in the Middle” (arXiv v3 11/2023, TACL): ở tác vụ hỏi đáp nhiều tài liệu và truy xuất key-value, kết quả thường tốt nhất khi thông tin liên quan nằm ở đầu hoặc cuối input và giảm rõ khi nằm ở giữa, trên các model được thử lúc đó.
• Chroma, “Context Rot” (2025-07-14) thử 18 model và thấy hiệu năng thay đổi đáng kể theo độ dài input, kể cả ở tác vụ đơn giản; ở phần LongMemEval, prompt tập trung cho kết quả tốt hơn rõ rệt prompt đầy đủ. Báo cáo nói rõ không giải thích cơ chế và không bao quát hết tình huống thực tế.

Bài này vì vậy không dựa vào giả định về cơ chế bên trong của một model cụ thể. Nó dựa vào hai thứ bạn tự kiểm được: mỗi mảnh context truy được tới một quyết định cần đưa ra (bảng trên), và kết quả cuối kiểm được bằng test. Các con số trong nguồn đo trên model và tác vụ tại thời điểm công bố; model bạn dùng hôm nay có thể khác.

Chạy lại case từ thư mục sạch

Tạo thư mục trống, ví dụ shop-lab, và chạy mọi lệnh trong đó. Ba file đã có ở mục trên (shop/clients/shipping.py bản lỗi, shop/api/checkout.py, shop/clients/inventory.py); tạo thêm năm file sau.

Output trong bài lấy từ lần chạy trên Linux với Python 3.14 ngày 2026-10-02. Các lệnh lọc dùng cat, grep, wc của shell kiểu Unix; macOS, Windows và các bản Python khác từ 3.10 chưa được thử.

shop/config.py:

INVENTORY_URL = "http://inventory.internal"
SHIPPING_URL = "http://carrier.internal"
INVENTORY_TIMEOUT = 0.5
SHIPPING_TIMEOUT = 0.5

shop/errors.py:

class UpstreamTimeout(Exception):
    def __init__(self, service):
        super().__init__(f"{service} timed out")
        self.service = service

shop/clients/http_json.py:

import json
import urllib.error
import urllib.request


def get_json(url, timeout=None):
    try:
        with urllib.request.urlopen(url, timeout=timeout) as response:
            return json.load(response)
    except urllib.error.URLError as exc:
        if isinstance(exc.reason, TimeoutError):
            raise TimeoutError(url) from exc
        raise

shop/api/steps.py (chỉ ghi log từng bước):

import logging
import time

from shop.errors import UpstreamTimeout

log = logging.getLogger("shop")


def timed(rid, step, call, *args):
    log.info("rid=%s step=%s start", rid, step)
    started = time.monotonic()
    try:
        result = call(*args)
    except UpstreamTimeout:
        elapsed = time.monotonic() - started
        log.warning("rid=%s step=%s timeout elapsed=%.2fs", rid, step, elapsed)
        raise
    elapsed = time.monotonic() - started
    log.info("rid=%s step=%s ok elapsed=%.2fs", rid, step, elapsed)
    return result

tests/test_checkout.py dựng hai server giả (kho nhanh, carrier chậm tùy test) trên cổng tự chọn:

import json
import logging
import threading
import time
import unittest
from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer

from shop import config
from shop.api.checkout import checkout

ORDER = {"sku": "A1", "qty": 1, "zip": "70000"}


class Upstream(BaseHTTPRequestHandler):
    delay = 0.0

    def do_GET(self):
        time.sleep(self.delay)
        body = json.dumps({"price": 4.5}).encode()
        try:
            self.send_response(200)
            self.send_header("Content-Length", str(len(body)))
            self.end_headers()
            self.wfile.write(body)
        except OSError:
            pass

    def log_message(self, *args):
        pass


def setUpModule():
    logging.basicConfig(
        filename="app.log", filemode="w", level=logging.INFO, format="%(message)s"
    )


class CheckoutTest(unittest.TestCase):
    def serve(self, delay):
        handler = type("Handler", (Upstream,), {"delay": delay})
        server = ThreadingHTTPServer(("127.0.0.1", 0), handler)
        threading.Thread(target=server.serve_forever, daemon=True).start()
        self.addCleanup(server.server_close)
        self.addCleanup(server.shutdown)
        return f"http://127.0.0.1:{server.server_port}"

    def setUp(self):
        config.INVENTORY_URL = self.serve(delay=0.0)

    def test_healthy_carrier_returns_200(self):
        config.SHIPPING_URL = self.serve(delay=0.0)
        status, body = checkout({"rid": "ok-1", **ORDER})
        self.assertEqual((status, body), (200, {"shipping": {"price": 4.5}}))

    def test_slow_carrier_returns_503_within_budget(self):
        config.SHIPPING_URL = self.serve(delay=1.5)
        started = time.monotonic()
        status, body = checkout({"rid": "slow-1", **ORDER})
        elapsed = round(time.monotonic() - started, 2)
        self.assertLess(elapsed, 1.0)
        self.assertEqual(
            (status, body), (503, {"error": "upstream_timeout", "service": "shipping"})
        )

Chạy test với bản lỗi. Lệnh lọc chỉ giữ các dòng kết quả:

python3 -m unittest discover -s tests 2>&1 | grep -E "^(FAIL|AssertionError|Ran|OK|FAILED)"

Kết quả khớp mảnh 3. Log thô gồm 8 dòng của hai request: ok-1 khỏe và slow-1 chậm.

cat app.log

rid=ok-1 step=inventory.reserve start
rid=ok-1 step=inventory.reserve ok elapsed=0.01s
rid=ok-1 step=shipping.quote start
rid=ok-1 step=shipping.quote ok elapsed=0.00s
rid=slow-1 step=inventory.reserve start
rid=slow-1 step=inventory.reserve ok elapsed=0.00s
rid=slow-1 step=shipping.quote start
rid=slow-1 step=shipping.quote ok elapsed=1.50s

Lệnh đầu lọc theo rid và in đúng bốn dòng ở mảnh 3. Lệnh sau đếm kích thước để thấy bộ “thừa” lớn cỡ nào, in ra bảng dưới đây:

grep "rid=slow-1" app.log
wc -l shop/*.py shop/*/*.py tests/*.py app.log

   4 shop/config.py
   4 shop/errors.py
  14 shop/api/checkout.py
  20 shop/api/steps.py
  13 shop/clients/http_json.py
  11 shop/clients/inventory.py
   7 shop/clients/shipping.py
  63 tests/test_checkout.py
   8 app.log
 144 total

Bây giờ sửa theo ví dụ cùng quy ước: truyền timeout và đổi TimeoutError thành UpstreamTimeout("shipping"). Thay nội dung shop/clients/shipping.py:

from shop import config
from shop.clients.http_json import get_json
from shop.errors import UpstreamTimeout


def shipping_quote(zip_code):
    url = f"{config.SHIPPING_URL}/quote?zip={zip_code}"
    try:
        return get_json(url, timeout=config.SHIPPING_TIMEOUT)
    except TimeoutError as exc:
        raise UpstreamTimeout("shipping") from exc

Chạy lại test và lọc log của request chậm:

python3 -m unittest discover -s tests 2>&1 | grep -E "^(FAIL|AssertionError|Ran|OK|FAILED)"
grep "rid=slow-1" app.log

Ran 2 tests in 2.014s
OK
rid=slow-1 step=inventory.reserve start
rid=slow-1 step=inventory.reserve ok elapsed=0.00s
rid=slow-1 step=shipping.quote start
rid=slow-1 step=shipping.quote timeout elapsed=0.50s

Dòng cuối của log đổi từ ok elapsed=1.50s sang timeout elapsed=0.50s: lời gọi bị cắt đúng ngân sách thay vì chờ carrier. Cả hai test đều đạt, nên đường chạy bình thường không bị phá.

Giới hạn và lỗi thường gặp

Giới hạn của bài

• Lab giả lập và thu nhỏ thời gian. Bài cho thấy bộ input chứa đủ dữ kiện để xác định và kiểm bản sửa bằng test; nó không đo xem agent hay model nào sửa đúng hơn nhờ bộ này, và chưa có phép so sánh thiếu, thừa, đủ trên model nào.
• “Đủ” không có nghĩa là ngắn nhất. Ở repo thật bộ đủ có thể lớn hơn nhiều; tiêu chí là không mảnh nào thiếu căn cứ và không mảnh nào thừa tác dụng.
• Ví dụ cùng quy ước phải đúng. Nếu inventory.py có lỗi, bản sửa sẽ sao chép lỗi đó; kiểm ví dụ bằng test hoặc lịch sử thay đổi trước khi dùng.
• Theo tài liệu, timeout của urllib áp cho các thao tác chặn như kết nối, nên không phải ngân sách tổng cho cả request. Muốn giới hạn tổng thời gian cần cơ chế khác; ngân sách 0,5 giây của lab đúng với carrier im lặng, không bao quát mọi kiểu phản hồi chậm.
• Nguồn về độ dài context đo trên model và tác vụ cụ thể ở thời điểm công bố; không có ngưỡng dùng chung.

Lỗi thường gặp

Học tiếp

• Tiêu chí hoàn tất có thể kiểm chứng: biến mảnh “cách kiểm” thành tiêu chí và verifier có thể thất bại.
• Sử dụng và viết skill: đưa quy trình lặp lại vào skill để khỏi dán lại mỗi lần.
• AI Agent Skills: phân biệt prompt, skill, quy tắc dự án, tool và harness.

Nguồn tham khảo

• Anthropic, Effective context engineering for AI agents, 2025-09-29.
• N. F. Liu và cộng sự, Lost in the Middle: How Language Models Use Long Contexts, arXiv:2307.03172 (v3, 2023-11-20), TACL.
• Chroma, Context Rot, 2025-07-14.
• Claude Code, Best practices, mục “Provide specific context in your prompts”.
• Python, urllib.request và socket.