Bài 5 — Sinh và cập nhật README từ codebase

Docstring mô tả "cây"; README mô tả "rừng". README là cửa vào của dự án: cài đặt, cách dùng, ví dụ, cấu trúc. README lỗi thời khiến người mới bỏ cuộc ngay phút đầu. Bài này agent sẽ tổng hợp README từ nhiều nguồn tín hiệu trong repo.

Nguồn sự thật cho README

Agent không đoán — nó thu thập từ:

• pyproject.toml / package.json — tên, version, dependency, script.
• Entry point / CLI — các lệnh chạy được.
• Public API — hàm/class được export.
• Ví dụ trong examples/ hoặc test.
• Biến môi trường trong .env.example.

def collect_readme_facts(repo):
    return {
        "name": read_project_name(repo),        # tu pyproject/package.json
        "install": detect_install_cmd(repo),      # pip install / npm i
        "entrypoints": find_cli_commands(repo),
        "public_api": list_exported_symbols(repo),
        "env": parse_env_example(repo),
    }

Các bước sinh README

• Thu thập "facts" như trên thành một object có cấu trúc.
• Đưa facts + một template README chuẩn vào prompt.
• Yêu cầu model điền template bằng facts — cấm bịa lệnh không có trong facts.
• Sinh mục Cài đặt, Cách dùng nhanh, Ví dụ, Cấu hình (env), Đóng góp.
• So sánh với README cũ (nếu có) và chỉ cập nhật phần lệch, giữ nội dung người viết tay (badge, logo, phần "Vì sao").
• Xuất ra PR để người duyệt.

Template ràng buộc

# {name}

{one_line_description}

## Cai dat

bash {install_cmd}

## Cach dung

{lang} {minimal_usage_example}

## Cau hinh

{env_table}

Model chỉ điền chỗ {...} bằng facts đã thu thập. Nếu một facts trống, để model ghi TODO thay vì bịa.

Khung tư duy: README là "hợp đồng" với người dùng

Mỗi lệnh trong README là một lời hứa "chạy được". Vì thế:

• Lệnh cài đặt phải trích từ file cấu hình thật, không đoán.
• Ví dụ dùng nên lấy từ test/examples đã pass, đảm bảo chạy được.
• Bảng env phải khớp .env.example.

Cập nhật thay vì viết lại

Khi README đã có, đừng để agent xóa sạch viết mới — bạn sẽ mất phần định tính quý (triết lý dự án, ảnh, badge CI). Chiến lược: section-diff — chỉ regenerate các mục cơ học (Cài đặt, API, env) và giữ nguyên mục do người viết. Đánh dấu ranh giới bằng comment mốc:

<!-- AGENT:BEGIN install -->
... phan agent quan ly ...
<!-- AGENT:END install -->

Agent chỉ được sửa giữa hai mốc. Đây là kỹ thuật quan trọng để agent và người cùng sở hữu một file mà không giẫm chân nhau.

Thuật toán cập nhật một mục có mốc

import re

def update_section(readme, name, new_content):
    begin = f"<!-- AGENT:BEGIN {name} -->"
    end = f"<!-- AGENT:END {name} -->"
    block = f"{begin}\n{new_content}\n{end}"
    pattern = re.compile(re.escape(begin) + r".*?" + re.escape(end), re.S)
    if pattern.search(readme):
        return pattern.sub(block, readme)   # thay noi dung giua 2 moc
    return readme + "\n\n" + block          # chua co thi them moi

Hàm này idempotent: chạy nhiều lần cho cùng facts thì README không đổi thêm — điều kiện quan trọng để agent không tạo diff nhiễu trên mỗi lần chạy CI.

Trích ví dụ dùng từ test đã pass

Một mục 'Cách dùng' đáng tin phải chạy được. Nguồn tốt nhất là test hoặc thư mục examples/ đã xanh. Agent có thể quét test tìm đoạn gọi public API rồi rút gọn thành ví dụ tối thiểu. Cách này bảo đảm mọi dòng trong README là lời hứa 'chạy được' có kiểm chứng, thay vì đoạn model tự chế có thể sai import hay sai tên hàm.

Sinh cả API reference tự động

Ngoài README, agent có thể xuất một trang API reference từ chính docstring đã sinh ở Bài 4 — ví dụ chạy pdoc hay sphinx-apidoc để render docstring thành HTML/Markdown. Vì reference bắt nguồn trực tiếp từ docstring (vốn đã được verify khớp chữ ký), nó tự động ít drift hơn tài liệu viết tay tách rời.

Sai lầm thường gặp

• Để agent viết lại toàn bộ README và xóa mất phần người viết. Luôn dùng mốc AGENT:BEGIN/END.
• Bịa lệnh cài đặt. pip install myproject trong khi package chưa lên PyPI. Chỉ dùng facts thật.
• Ví dụ không chạy được. Lấy ví dụ từ test đã pass, đừng để model tự chế.
• Bảng env lệch .env.example. Sinh env trực tiếp từ file nguồn.
• Sinh README một lần rồi thôi. README cũng drift — gắn nó vào quy trình Verify (Bài 6-7).

Kết bài: agent giờ chăm được cả docstring lẫn README theo nguyên tắc "cùng sở hữu". Bài 6 ta xây bước then chốt: phát hiện drift tự động.