Xây repository thân thiện với coding agent

1. Model và prompt chưa đủ: vai trò của repository

Jim Thompson mở đầu bằng nhận xét rằng các AI coding assistant như GitHub Copilot và Codex đang ngày càng làm được nhiều việc phát triển phần mềm (theo Jim, video đăng ngày 01/11/2026). Nhưng để có kết quả đáng tin cậy thì cần nhiều hơn việc chọn một model giỏi hay viết một prompt tốt: bản thân repository cũng đóng một vai trò quan trọng.

Câu hỏi anh đặt ra là điều gì làm một repository trở nên thân thiện với AI coding agent, các agent workflow khác nhau vận hành ra sao, và những practice nào giúp agent tạo ra kết quả đáng tin cậy, kiểm chứng được (video đăng ngày 01/11/2026). Anh minh hoạ bằng một project thật mà anh đã áp dụng những ý tưởng này, gồm cả những thứ chạy tốt và những chỗ vẫn cần cải thiện. Anh bắt đầu bằng việc xác lập một số thuật ngữ quanh agent workflow.

Theo Jim (video đăng ngày 01/11/2026), một agent workflow mô tả cách một coding assistant tiếp cận một task, cách nó thực hiện thay đổi, cách nó đưa feedback vào, và cách kết quả được kiểm chứng. Hai khái niệm hữu ích ở đây là workflow open-loop và closed-loop. Sự phân biệt này quan trọng vì nó giúp chúng ta hiểu phần nào agent chịu trách nhiệm và phần nào vẫn là trách nhiệm của developer. Nó cũng giúp giải thích vì sao các capability của repository lại quan trọng đến vậy: một agent có thể có khả năng thay đổi code, nhưng nếu repository không cho nó một cách đáng tin cậy để kiểm tra các thay đổi đó, khả năng tự hoàn thành task của nó bị giới hạn.

2. Open-loop và closed-loop: hai kiểu agent workflow

Bên trái slide là workflow open-loop. Developer đưa ra một yêu cầu và agent tạo ra một đề xuất: có thể là code, một bản design hay một khuyến nghị. Theo Jim (video đăng ngày 01/11/2026), đặc điểm quan trọng là agent không tự động chạy check rồi dùng kết quả để sửa output của mình. Nó trao kết quả lại cho developer, và developer là người chịu trách nhiệm xác định kết quả đó có đúng không.

Bên phải là workflow closed-loop. Ở đây agent implement một thay đổi, chạy các check liên quan và đánh giá kết quả. Nếu một check fail và vấn đề có thể sửa trong các giới hạn đã đặt ra, agent thực hiện một thay đổi khác rồi chạy lại check. Theo Jim (video đăng ngày 01/11/2026), vòng feedback này tiếp diễn cho tới khi đạt acceptance criteria hoặc chạm một điều kiện dừng.

Anh lưu ý hai kết cục có thể xảy ra ở cuối sơ đồ. Nếu đạt các tiêu chí, công việc sẵn sàng cho bước developer review bắt buộc. Nếu agent bị chặn hoặc chạm giới hạn, nó báo cáo vấn đề và escalate, thay vì tiếp tục vô thời hạn (theo Jim, video đăng ngày 01/11/2026).

Đó là một sự phân biệt quan trọng: theo Jim (video đăng ngày 01/11/2026), closed-loop không có nghĩa là agent có quyền tự chủ không giới hạn. Developer vẫn review và xác nhận kết quả trước khi chấp nhận. Cả hai workflow đều hữu ích; điều cốt lõi là hiểu việc kiểm chứng và sửa lỗi được xử lý thế nào. Và điều đó dẫn tới repository.

3. Workflow dẫn dắt agent, repository giúp thực thi

Ý tưởng trung tâm của bài trình bày, theo Jim (video đăng ngày 01/11/2026), là phát triển phần mềm theo kiểu agentic phụ thuộc vào hai thứ phối hợp với nhau. Thứ nhất là workflow, thứ quyết định agent thực hiện công việc thế nào. Thứ hai là repository, nơi cung cấp tri thức, feedback và ranh giới cần thiết để thực hiện công việc một cách đáng tin cậy.

Hãy nghĩ xem một agent cần biết những gì: code liên quan nằm ở đâu? Nó phải theo những conventions nào? Nó được phép thay đổi những gì? Và làm sao nó xác định được thay đổi có thật sự chạy đúng không? Theo Jim (video đăng ngày 01/11/2026), một repository thân thiện với agent làm cho các câu trả lời này dễ tiếp cận. Sự phân biệt anh muốn nhấn mạnh là: workflow dẫn dắt agent, còn repository giúp việc thực thi đáng tin cậy.

4. Năm capability quan sát được của repository

Thay vì định nghĩa repository thân thiện với agent bằng các tool hay file cụ thể, Jim thấy hữu ích hơn khi định nghĩa nó qua các capability quan sát được (video đăng ngày 01/11/2026). Có năm capability anh muốn làm nổi bật:

1. Discover: agent có tìm được code liên quan và tri thức của project không? (theo Jim, video đăng ngày 01/11/2026)
2. Understand: nó có xác định được các conventions và constraints áp dụng ở đây không? (theo Jim, video đăng ngày 01/11/2026)
3. Act within bounds: nó có biết cái gì nằm trong scope và khi nào cần con người góp ý không? (theo Jim, video đăng ngày 01/11/2026)
4. Verify: nó có xác lập được rằng một thay đổi thật sự chạy đúng không? (theo Jim, video đăng ngày 01/11/2026)
5. Resume: một session khác có tiếp tục được từ chỗ session trước dừng lại không? (theo Jim, video đăng ngày 01/11/2026)

Bảng trên slide cho thấy những bằng chứng mà ta có thể kỳ vọng tìm thấy trong repository. Ví dụ, discovery có thể được hỗ trợ bằng một README và một module map, còn verification cần các check chạy được và tiêu chí hoàn thành rõ ràng. Theo Jim (video đăng ngày 01/11/2026), năm capability này là một khung hữu ích để đánh giá một repository, độc lập với việc đang dùng coding assistant nào.

5. Discover: tổ chức tri thức của project theo lớp

Capability đầu tiên là khả năng được khám phá (discoverability). Theo Jim (video đăng ngày 01/11/2026), một coding agent cần một điểm xuất phát cho nó biết project được tổ chức thế nào và tìm thông tin bổ sung ở đâu. Đó có thể là một README, hoặc một file hướng dẫn cho agent như agents.md, có link tới tài liệu architecture, mô tả module, API contract và các lệnh verification.

Nhưng có một nguyên tắc thiết kế quan trọng ở đây: chúng ta không muốn nhét mọi chi tiết vào một file hướng dẫn khổng lồ. Thay vào đó, theo Jim (video đăng ngày 01/11/2026), ta muốn tổ chức tri thức theo lớp. Agent bắt đầu từ một task, tìm ra các module liên quan, đi theo link tới các dependency và contract áp dụng, rồi xem xét code và test cụ thể.

Theo Jim (video đăng ngày 01/11/2026), cách tiếp cận này giúp agent lấy được context liên quan mà không phải nạp toàn bộ tài liệu của repository. Mục tiêu rất đơn giản: làm cho đúng tri thức cần thiết dễ tìm, mà không phải nạp mọi thứ. Slide của phần này ghi bốn ý: một điểm vào rõ ràng, tri thức chính thức được giữ trong các file có version control, khám phá dần dần từ task tới module, dependency, contract rồi tới code và test, và nạp context có chọn lọc bằng cách để tài liệu chi tiết phía sau các link.

6. Understand: conventions và constraints

Khi agent đã tìm thấy code liên quan, theo Jim (video đăng ngày 01/11/2026), nó cần hiểu project kỳ vọng code đó được phát triển thế nào. Việc này gồm coding conventions, các constraint về architecture, lệnh để build và test, và quy tắc về những gì nên hoặc không nên bị sửa. Các file như agents.md có thể cung cấp hướng dẫn này, tuỳ vào việc coding assistant hỗ trợ những gì.

Slide "Help Agents Understand the Project Conventions and Constraints" của phần này liệt kê thêm: đặt hướng dẫn gần code mà nó điều chỉnh khi agent hỗ trợ hướng dẫn phân cấp, để ghi chú debug, tiến độ task và tutorial chi tiết ở các tài liệu riêng có link, tránh hướng dẫn trùng lặp, lỗi thời hay mâu thuẫn giữa các file hướng dẫn, và theo conventions của coding assistant, chẳng hạn AGENTS.md (slide trong video đăng ngày 01/11/2026).

7. Act within bounds: ranh giới cho việc tự thực thi

Theo Jim (video đăng ngày 01/11/2026), trước khi bắt đầu implement, task nên có scope rõ ràng, acceptance criteria và mọi constraint về tương thích. Agent cũng nên biết những hành động nào nó có thể tự làm và những hành động nào cần developer cho phép. Ví dụ, một agent có thể được phép sửa code và chạy unit test, nhưng cần được duyệt trước khi thực hiện một số thao tác GUI nhất định hoặc thay đổi lớn về architecture.

Một practice hữu ích khác, theo Jim (video đăng ngày 01/11/2026), là giới hạn số lần thử sửa lỗi. Nếu agent cứ gặp đi gặp lại cùng một lỗi, chúng ta không muốn nó tiếp tục vô thời hạn, hay bắt đầu làm yếu các test đi chỉ để có một kết quả pass. Thay vào đó, nó nên dừng lại, báo cáo những gì đã thử và xin hướng dẫn.

Jim cũng thích chia các task phát triển lớn thành nhiều phase, với bước developer xác nhận ở mỗi ranh giới phase (video đăng ngày 01/11/2026). Theo anh, cách đó cho phép agent làm việc độc lập trong một phase đã được duyệt, trong khi con người vẫn giữ quyền kiểm soát hướng đi của project. Ý tưởng là cho agent quyền tự chủ hữu ích, nhưng với giới hạn rõ ràng về lúc nào phải dừng và xin ý kiến con người.

8. Verify: kiểm chứng thay đổi bằng check chạy được

Theo Jim (video đăng ngày 01/11/2026), verification đặc biệt quan trọng với workflow closed-loop: một agent không thể sửa công việc của mình một cách đáng tin cậy nếu nó không có cách xác định cái gì thành công và cái gì thất bại. Điều đó có nghĩa repository nên chứa các check chạy được, gồm test, build, linting và type checking ở những chỗ phù hợp. Và các check đó cần dễ tìm thấy và tái lập được.

Theo Jim (video đăng ngày 01/11/2026), repository nên ghi lại các điều kiện môi trường cần có trước và đúng các lệnh cần thiết để chạy check. Cũng hữu ích khi phân biệt giữa check có mục tiêu hẹp và verification rộng hơn: trong lúc phát triển, agent có thể chạy một unit test tập trung; trước khi hoàn thành task, nó có thể cần chạy một bộ regression lớn hơn.

Cuối cùng, theo Jim (video đăng ngày 01/11/2026), agent cần báo cáo điều gì đã thật sự xảy ra. Một test pass khác với một test không chạy được vì thiếu một dependency. Và một check chưa bao giờ được chạy thì không nên bị báo là thành công. Đây là điều làm cho feedback chạy được trở nên có giá trị: nó cho agent bằng chứng để chẩn đoán vấn đề và cải thiện công việc của mình.

9. Resume: làm việc liên tục qua nhiều session

Một thách thức khác của phát triển phần mềm có AI hỗ trợ, theo Jim (video đăng ngày 01/11/2026), là tính liên tục giữa các session. Các task phát triển lớn có thể cần nhiều lượt tương tác, thậm chí nhiều session agent riêng biệt mới xong. Chúng ta không nên phụ thuộc vào việc agent nhớ hết mọi thứ từ một cuộc hội thoại trước đó.

Thay vào đó, theo Jim (video đăng ngày 01/11/2026), repository nên lưu giữ thông tin cần thiết để tiếp tục công việc: implementation plan, các task đã xong, các quyết định, các file đã đổi, kết quả verification và các vấn đề còn tồn đọng.

Jim thấy hữu ích khi phân biệt giữa plan và checkpoint (video đăng ngày 01/11/2026). Plan mô tả những gì cần làm và thành công sẽ được đánh giá thế nào. Checkpoint mô tả trạng thái hiện tại: những gì đã xong, những gì đã được verify, và những gì còn chưa giải quyết.

Theo Jim (video đăng ngày 01/11/2026), lượng tài liệu nên tương xứng với độ phức tạp của task. Mục tiêu là để một session agent mới có thể tiếp tục công việc mà không dựa vào lịch sử hội thoại trước đó.

10. Một repository minh hoạ: các capability nằm ở đâu

Jim đưa ra một ví dụ về cách các capability đó có thể xuất hiện trong một repository (video đăng ngày 01/11/2026). Ở trên cùng, README.md là điểm vào, còn AGENTS.md cung cấp hướng dẫn cho coding assistant. CONTRIBUTING.md mô tả workflow phát triển và verification. Dưới docs có thông tin architecture, các quyết định architecture và implementation plan.

Cây thư mục trên slide:

repository/
├── README.md              # Entry point, module map, setup, links
├── AGENTS.md              # Example assistant instruction entry point
├── CONTRIBUTING.md        # Development and verification workflow
├── docs/
│   ├── architecture.md    # Components, boundaries, dependencies
│   ├── decisions/         # Architectural decisions and rationale
│   └── plans/             # Substantial task plans and progress
├── src/                   # Implementation and applicable local guidance
├── tests/                 # Executable behavior checks
├── scripts/               # Setup and verification entry points
└── CHECKPOINT.md          # Current handoff state when needed

Theo Jim (video đăng ngày 01/11/2026), code nguồn và test được tổ chức trong các thư mục tương ứng, còn scripts cung cấp các điểm vào tiện lợi cho setup và verification. Cuối cùng, một file checkpoint có thể ghi lại trạng thái hiện tại của một task đang làm dở.

Theo Jim (video đăng ngày 01/11/2026), đây chỉ là một cấu trúc minh hoạ: không phải repository nào cũng cần đúng những file hay thư mục này. Điều quan trọng là các capability có mặt và agent có thể tìm ra cách dùng chúng. Cấu trúc nên phục vụ workflow phát triển, chứ không trở thành tài liệu viết ra cho có.

11. Repository thân thiện với agent và subagent

Theo Jim (video đăng ngày 01/11/2026), repository thân thiện với agent cũng có thể giúp dùng subagent hiệu quả. Một subagent hữu ích khi một task lớn có thể chia nhỏ thành các phần việc nhỏ hơn có giới hạn rõ. Ví dụ, một subagent có thể tìm hiểu một module trong khi một subagent khác xem xét các test liên quan.

Để làm được vậy, theo Jim (video đăng ngày 01/11/2026), mỗi phần việc cần mục tiêu, scope, constraint và sản phẩm đầu ra rõ ràng. Repository cũng cần định nghĩa rõ trách nhiệm và interface của từng module để các subagent làm việc với mức chồng chéo tối thiểu. Khi nhiều subagent cùng sửa code, các branch hoặc worktree riêng có thể cô lập thay đổi của chúng.

Theo Jim (video đăng ngày 01/11/2026), mỗi subagent nên trả về bằng chứng về những gì nó đã làm, những gì nó đã verify và mọi vấn đề còn chưa giải quyết. Agent chính vẫn chịu trách nhiệm tích hợp và xác nhận cuối cùng. Điểm quan trọng là một repository được tổ chức tốt làm cho việc giao việc dễ hơn, nhưng nên giao việc khi lợi ích của nó xứng với chi phí phối hợp thêm.

12. Đo và cải thiện mức thân thiện với agent

Làm sao biết một repository có thật sự thân thiện với agent không? Theo Jim (video đăng ngày 01/11/2026), một cách là đánh giá nó bằng các task phát triển mang tính đại diện. Ta có thể xem task mất bao lâu, cần bao nhiêu lần thử sửa, developer phải can thiệp thường xuyên tới mức nào, và cần làm lại bao nhiêu trong lúc review.

Ta cũng có thể tìm các điểm ma sát (friction), theo Jim (video đăng ngày 01/11/2026): agent có chật vật tìm code liên quan không? Nó có hiểu sai các constraint của project không? Các lệnh verification có khó chạy không? Nó có tiếp tục công việc thành công không? Những quan sát này giúp xác định các cải tiến cho repository. Và sau khi cải tiến, ta có thể lặp lại các task tương tự để xem quá trình phát triển có hiệu quả hơn không.

Theo Jim (video đăng ngày 01/11/2026), mục tiêu không đơn thuần là tạo ra nhiều tài liệu hơn, mà là làm cho repository hỗ trợ công việc phát triển đáng tin cậy, đã được kiểm chứng, tốt hơn một cách đo được.

13. Case study: ide-tester, harness smoke test cho VS Code

Jim cho xem cách anh đã áp dụng những ý tưởng này trong một project thật tên là ide-tester. Theo Jim (video đăng ngày 01/11/2026), đây là một harness smoke test viết bằng TypeScript cho Visual Studio Code. Mục đích của nó là khởi chạy một instance VS Code riêng và tự động hoá các check cơ bản: sửa file, thao tác Git, cài extension, viết code Python và Copilot Chat.

Theo Jim (video đăng ngày 01/11/2026), cách test của project dựa trên bộ smoke test tự động mà chính project VS Code dùng, và điều chỉnh cách đó cho nhu cầu test riêng của ide-tester. Nó dùng các profile cô lập và workspace dùng một lần rồi bỏ, và nó verify các kết quả quan sát được thay vì đơn thuần giả định rằng một thao tác UI đã thành công. Nó cũng kiểm tra kết quả và trạng thái dọn dẹp. Với Copilot Chat, harness hỗ trợ hoặc một service mock, hoặc backend Copilot thật.

Project cũng có một số constraint thực thi quan trọng, theo Jim (video đăng ngày 01/11/2026): đặc biệt, test GUI cần một môi trường desktop đã được cho phép và chuẩn bị sẵn. Điều đó làm nó thành một ví dụ hữu ích, vì nó đòi hỏi nhiều hơn việc sinh code: nó cần hướng dẫn rõ ràng, ranh giới thực thi, verification và sự chấp thuận của developer. Project có sẵn trên GitHub, và anh dùng cấu trúc repository cùng các practice phát triển của nó để minh hoạ những khái niệm đã nói.

14. Cấu trúc thật của repo ide-tester

Đây là cấu trúc repository thật, và Jim chỉ ra vài điểm giống với cấu trúc minh hoạ trước đó (video đăng ngày 01/11/2026). Ở thư mục gốc, README.md cung cấp thông tin project và điều hướng, còn AGENTS.md chứa hướng dẫn dùng chung và các quy tắc cho phép. Thư mục architectures chứa solution design, còn specifications giữ lại các yêu cầu và thông tin backlog. Dưới docs, các implementation plan ghi lại quyết định, tiến độ và kết quả xác nhận.

Cây thư mục trên slide:

ide-tester/
├── README.md                    # Current scope, setup, architecture diagram, navigation
├── AGENTS.md                    # Shared instructions, preservation and authorization
├── architectures/               # Solution design, CALM model, observations
├── specifications/              # Retained requirements and historical backlogs
├── docs/
│   ├── implementation-plans/    # Plans, decisions, progress and validation records
│   ├── research/                # Feasibility findings and supporting research
│   └── preserved-python-environment.md
├── .agents/skills/              # Backlog, planning, execution, issue and PR workflows
├── .github/                     # Issue and pull request templates
└── smoke/                       # Active TypeScript implementation
    ├── AGENTS.md                # Local commands, module map and execution contracts
    ├── README.md                # Setup, qualified compatibility, usage and recovery
    ├── CODING_STANDARDS.md
    ├── DEVELOPMENT_WORKFLOW.md
    ├── package.json, package-lock.json, .npmrc
    ├── src/, tests/, helper/    # Implementation, non-GUI tests and helper extension
    └── scripts/                 # GUI command bootstrap, parsing and reporting

Một bổ sung thú vị, theo Jim (video đăng ngày 01/11/2026), là thư mục .agents/skills. Các skill này cung cấp workflow lặp lại được cho các hoạt động như lập kế hoạch, thực thi các phase implementation, và làm việc với GitHub issue và pull request.

Phần implementation TypeScript nằm dưới thư mục smoke. Jim lưu ý rằng smoke có agents.md riêng, cùng coding standards và development workflow riêng (video đăng ngày 01/11/2026). Theo anh, cách này cho phép project tách các quy tắc áp dụng cho cả repository khỏi các hướng dẫn riêng cho smoke tester.

Một file bạn có thể nhận ra là đang thiếu: checkpoint.md. Theo Jim (video đăng ngày 01/11/2026), cấu trúc này là một ví dụ thực tế của tri thức project theo lớp và hướng dẫn theo từng ngữ cảnh.

15. ide-tester áp dụng năm capability thế nào

Bảng tiếp theo nối các capability đã nói với các artifact thật trong ide-tester. Theo Jim (video đăng ngày 01/11/2026), với discovery, repository cung cấp các điểm vào và thông tin về trách nhiệm của từng module để agent xác định được phần implementation liên quan. Với understanding, nó dùng hướng dẫn dùng chung, hướng dẫn cục bộ và coding standards. Thông tin architecture được duy trì dưới architectures, còn các quyết định và lý do cũng được ghi trong implementation plan.

Với việc tự thực thi, theo Jim (video đăng ngày 01/11/2026), development workflow định nghĩa việc lập kế hoạch, test-driven development, review, và developer xác nhận ở các ranh giới phase. Nó cũng đặt ra các giới hạn cụ thể. Ví dụ, agent phải escalate sau bốn lần thử sửa cùng một vấn đề không thành công. Và việc chạy GUI cần được cho phép riêng vì nó tương tác với một môi trường desktop thật. File AGENTS.md gốc của repo ghi quy tắc này là dừng sau bốn vòng sửa không thành công cho cùng một lỗi rồi hỏi developer (đọc ngày 01/11/2026).

Với verification, theo Jim (video đăng ngày 01/11/2026), repository cung cấp lệnh cho compile, linting, formatting và các test không cần GUI, cùng một quy trình riêng cho việc xác nhận GUI đã được cho phép. Điểm quan trọng là đây không chỉ là những lời khuyên: chúng được hỗ trợ bởi các artifact thật trong repository và các quy trình chạy được.

Slide tiếp nối có ba dòng: Verify: Results, Resume và Review. Một practice đặc biệt quan trọng trong ide-tester, theo Jim (video đăng ngày 01/11/2026), là verification độc lập. Ví dụ, khi test thao tác lưu file, harness không đơn thuần giả định file đã được lưu vì thao tác GUI đã hoàn tất: nó kiểm tra nội dung file kết quả một cách độc lập. Phần báo cáo cũng phân biệt giữa passed, failed, blocked, lỗi của harness, và các check không được chạy.

Với resumability, theo Jim (video đăng ngày 01/11/2026), các implementation plan lưu giữ tiến độ task, bằng chứng verification và sự chấp thuận của developer. Repository không dùng một file CHECKPOINT.md ở gốc; thay vào đó, các plan và hướng dẫn về gate hiện tại cung cấp thông tin bàn giao. Slide tiếp nối ghi bằng chứng cho Resume là "Issue #50 plan and execution record" (slide trong video đăng ngày 01/11/2026).

Cuối cùng, theo Jim (video đăng ngày 01/11/2026), các template GitHub issue, template pull request và các skill của repository đưa acceptance criteria và bằng chứng verification vào quy trình bàn giao. Đây là một ví dụ về việc điều chỉnh các capability cho phù hợp với repository, thay vì đòi hỏi đúng một cấu trúc cố định.

16. Skill của repository: biến hướng dẫn thành workflow lặp lại được

Theo Jim (video đăng ngày 01/11/2026), một trong những khía cạnh thú vị hơn của repository này là việc dùng agent skill. Một skill đóng gói hướng dẫn để thực hiện một hoạt động phát triển lặp lại được. Trong ide-tester, anh đã định nghĩa skill cho một số giai đoạn của vòng đời phát triển:

• generate-milestone-user-stories: sinh user story từ một milestone được chọn, kèm acceptance criteria và dependency (theo Jim, video đăng ngày 01/11/2026).
• create-github-issue: tạo GitHub issue từ các story đó (theo Jim, video đăng ngày 01/11/2026).
• plan-user-story: skill lập kế hoạch xem xét một story và tạo ra implementation plan chia thành các phase, có yêu cầu verification và các checkpoint cho developer (theo Jim, video đăng ngày 01/11/2026).
• execute-plan: làm qua một phase đã được cho phép, cập nhật tiến độ và ghi lại bằng chứng verification. Quan trọng là nó dừng ở mỗi ranh giới phase để developer xác nhận, thay vì tự động đi qua cả plan (theo Jim, video đăng ngày 01/11/2026).
• create-pull-request: chuẩn bị thông tin bàn giao, gồm các thay đổi thật, acceptance criteria và kết quả verification (theo Jim, video đăng ngày 01/11/2026).

Jim lưu ý rằng các skill này có ranh giới tường minh (video đăng ngày 01/11/2026). Tạo một issue không đồng nghĩa với cho phép implement. Duyệt một plan là việc tách biệt với cho phép thực thi. Tạo một pull request không đồng nghĩa với cho phép merge.

Theo Jim (video đăng ngày 01/11/2026), đây là cách hướng dẫn trong repository có thể được biến thành các workflow lặp lại được mà vẫn giữ quyền kiểm soát của developer. Nó cũng minh hoạ cách skill và các capability của repository bổ trợ cho nhau: skill định nghĩa quy trình, còn repository cung cấp tri thức và công cụ cần thiết để thực hiện quy trình đó.

17. ide-tester chưa hoàn hảo: những khoảng trống còn lại

Jim cũng muốn nhấn mạnh rằng ide-tester không phải một ví dụ hoàn hảo: có những chỗ repository có thể trở nên thân thiện với agent hơn (video đăng ngày 01/11/2026). Một số vấn đề phản ánh cách project đã phát triển. ide-tester bắt đầu là một project greenfield, và phần lớn giai đoạn phát triển ban đầu là nghiên cứu và đánh giá các hướng tiếp cận công nghệ khác nhau. Trong quá trình đó, một số hướng không chạy như kỳ vọng, và yêu cầu cùng acceptance criteria phải được sửa lại khi anh và nhóm hiểu thêm.

Kết quả là, theo Jim (video đăng ngày 01/11/2026), các file hướng dẫn và implementation plan tích luỹ một lượng lớn thông tin lịch sử, gồm acceptance criteria thay đổi, các hướng tiếp cận thất bại và kết quả thực thi. Giữ lại lịch sử đó hữu ích trong lúc phát triển, nhưng nó cũng tạo ra một số thách thức.

Theo Jim (video đăng ngày 01/11/2026), một số file hướng dẫn giờ chứa lịch sử dài và thay đổi thường xuyên, và thông tin trạng thái bị lặp lại giữa các file README và file hướng dẫn. Các implementation plan dài cũng giữ lại những yêu cầu đã bị thay thế bên cạnh các yêu cầu hiện hành. Điều này làm cho một agent bắt đầu session mới khó phân biệt cái gì đang còn liên quan với cái gì đã là lịch sử. Bảng trên slide ghi tác động: tăng lượng context phải dùng, khó nhận ra hướng dẫn hiện hành, và khó tiếp tục công việc hơn (slide trong video đăng ngày 01/11/2026).

Cách tiếp cận Jim đề xuất (video đăng ngày 01/11/2026) là giữ các hướng dẫn ổn định ngắn gọn, cung cấp một bản tóm tắt gọn về trạng thái hiện tại, và lưu lịch sử nghiên cứu cùng lịch sử thực thi chi tiết trong các tài liệu có link. Như vậy, chúng ta vẫn giữ được các bài học rút ra mà không bắt agent phải xử lý toàn bộ lịch sử đó cho mỗi task.

Theo Jim (video đăng ngày 01/11/2026), điều này củng cố một điểm quan trọng: mức thân thiện với agent không phải là một bài tập cấu hình làm một lần. Nó là thứ cần tiến hoá khi project trưởng thành và khi chúng ta học được cái gì hiệu quả.

18. Năm điều rút ra và một câu hỏi để bắt đầu

Jim khép lại bằng năm điều rút ra (video đăng ngày 01/11/2026):

1. Agent workflow và repository cần phối hợp với nhau. Workflow quyết định cách agent vận hành, còn repository cung cấp môi trường để thực thi đáng tin cậy (theo Jim, video đăng ngày 01/11/2026).
2. Làm cho tri thức dành cho agent dễ khám phá. Agent cần điểm vào rõ ràng, thông tin architecture, conventions của project, và hướng dẫn liên quan tới phần code chúng đang làm (theo Jim, video đăng ngày 01/11/2026).
3. Đặt ranh giới cho việc tự thực thi. Định nghĩa scope, acceptance criteria, giới hạn số lần sửa và các gate để developer review (theo Jim, video đăng ngày 01/11/2026).
4. Cho phép verification closed-loop. Cung cấp check chạy được và bằng chứng quan sát được để agent xác định lỗi, sửa vấn đề và chứng minh những gì chúng đã verify (theo Jim, video đăng ngày 01/11/2026).
5. Giữ tính liên tục. Plan, quyết định, bản ghi tiến độ và kết quả verification nên cho phép công việc tiếp tục qua các session mà không dựa vào lịch sử hội thoại (theo Jim, video đăng ngày 01/11/2026).

Thông điệp lớn hơn, theo Jim (video đăng ngày 01/11/2026), là xây dựng một repository thân thiện với agent không phải chuyện thêm một file cụ thể hay chọn một coding assistant cụ thể. Đó là chuyện tạo ra một môi trường nơi agent có thể hiểu project, hành động trong ranh giới rõ ràng, verify kết quả của mình và bàn giao công việc một cách đáng tin cậy.

Anh để lại ý tưởng trung tâm của bài trình bày: workflow quyết định cách một agent làm việc; repository quyết định nó có thể làm việc đáng tin cậy tới mức nào. Rồi anh gợi ý hãy chọn một repository và tự hỏi: một assistant có tìm được đúng context, hành động trong ranh giới rõ ràng, verify công việc của nó, và để lại đủ bằng chứng để người khác review hoặc tiếp tục công việc không? Theo Jim (video đăng ngày 01/11/2026), đừng bắt đầu bằng câu hỏi team mình đã có đúng model chưa; hãy bắt đầu bằng việc làm cho một repository sẵn sàng cho công việc đáng tin cậy.