Từ một file AGENTS.md quá tải đến knowledge layer cho coding agent

Một file hướng dẫn chỉ đủ ở giai đoạn đầu

Khi bắt đầu đưa coding agent vào quy trình phát triển phần mềm, tôi nghĩ bài toán khá đơn giản: viết một file hướng dẫn đủ rõ, mô tả convention của dự án, yêu cầu agent đọc trước khi implement và bổ sung một số guardrail quan trọng. Với Codex, file đó thường là AGENTS.md. Với Claude Code, vai trò tương tự thuộc về CLAUDE.md.

Cách này hoạt động khá tốt trong giai đoạn đầu. Một repository nhỏ, ít module, số lượng quyết định kiến trúc chưa nhiều và phần lớn context vẫn có thể suy ra trực tiếp từ source code. Tôi chỉ cần ghi một số điều cơ bản như cách build project, cách chạy test, naming convention, dependency nào không được thêm và những thư mục nào agent không nên thay đổi.

Sau đó dự án lớn dần.

Trong những hệ thống lớn mà tôi đã tham gia, một repository ban đầu có thể chỉ chứa vài service, nhưng sau một thời gian sẽ có thêm frontend, backend, worker, shared libraries, infrastructure code, deployment manifest, event contract và nhiều luồng tích hợp khác nhau. Một số dự án chuyển thành monorepo. Một số khác vẫn tách repository nhưng chia sẻ cùng một bộ nguyên tắc kiến trúc. Những rule tưởng như đơn giản ban đầu bắt đầu phụ thuộc vào từng service, từng domain và từng loại thay đổi.

Phản ứng khi đó cũng giống nhiều team khác: tiếp tục bổ sung nội dung vào file hướng dẫn.

Từ một file vài chục dòng, AGENTS.md dần chứa:

• Tổng quan hệ thống.
• Trách nhiệm của từng service.
• Quy tắc Clean Architecture.
• Convention cho .NET, Python, Angular hoặc React.
• Cách dùng Kafka và Outbox.
• Quy tắc tenant isolation.
• API contract.
• Event schema.
• Hướng dẫn migration.
• Runbook xử lý lỗi.
• Danh sách các lỗi coding agent từng mắc phải.

Ở một thời điểm nào đó, tôi nhận ra file hướng dẫn không còn thực sự là một file hướng dẫn. Nó đã trở thành một wiki thu nhỏ được nhồi vào prompt mặc định của agent.

Khi nhiều context hơn lại làm agent kém chính xác hơn

Khi coding agent làm sai, phản ứng đầu tiên thường là cho rằng nó chưa có đủ context. Thế là rule được viết thêm, tài liệu được mô tả chi tiết hơn và agent bị yêu cầu đọc nhiều hơn trước khi bắt đầu.

Cách làm đó có giới hạn.

Khi một task chỉ liên quan đến Kafka consumer trong một worker service, agent vẫn phải mang theo cả convention của frontend, rule của database migration, kiến trúc retrieval, model selection và những hướng dẫn không liên quan. Những thông tin quan trọng không còn nổi bật. Chúng bị đặt ngang hàng với hàng trăm dòng context khác.

Có những lần agent đã đọc đúng file nhưng vẫn bỏ qua một rule nằm sâu ở phía dưới. Có lúc nó follow convention của service khác, có lúc lại áp dụng một quyết định kiến trúc cũ vào implementation mới. Nguy hiểm hơn là khi source code và tài liệu đã lệch nhau, agent không báo conflict mà tự hợp lý hóa implementation hiện tại thành design chính thức.

Từ đó, vấn đề cần giải quyết không còn là thiếu tài liệu. Codebase đang thiếu một kiến trúc để phân phối đúng context cho đúng task.

Một coding agent không cần biết toàn bộ hệ thống trong mỗi lần thực thi. Nó cần biết chính xác phần nào của hệ thống đang bị tác động, những boundary nào phải giữ, decision nào còn hiệu lực và source nào đáng tin hơn khi thông tin mâu thuẫn.

OKF và một cách tổ chức knowledge có cấu trúc

Open Knowledge Format, hay OKF, là một đặc tả mở để biểu diễn knowledge bằng các file Markdown có YAML frontmatter và được tổ chức theo cây thư mục.

OKF được Google Cloud khởi xướng và công bố công khai vào ngày 12/6/2026. Đặc tả này phát triển từ mô hình mà Google gọi là “LLM-wiki”: knowledge được viết thành những tài liệu nhỏ, có cấu trúc, có thể đọc bởi cả con người lẫn agent. Mục tiêu của Google không phải tạo thêm một knowledge platform độc quyền, mà chuẩn hóa mô hình đó thành một format mở, portable và interoperable. Phiên bản ban đầu tập trung vào cách đóng gói concept bằng Markdown; OKF v0.2 sau đó bổ sung rõ hơn các tín hiệu về provenance, verification, freshness và lifecycle. Các mốc này được Google Cloud công bố trong bài giới thiệu OKF và bản cập nhật v0.2.

Điều đáng chú ý không nằm ở việc OKF dùng Markdown. Giá trị lớn hơn là cách nó coi mỗi đơn vị tri thức như một concept có định danh, metadata, trạng thái vòng đời và mối liên kết với các concept khác. Với coding agent, đây là một cách tổ chức context thực dụng hơn việc đưa mọi thứ vào một file instruction duy nhất.

Đặt vào bối cảnh coding agent, cách tiếp cận này khá tự nhiên.

Thay vì đưa toàn bộ kiến trúc vào AGENTS.md, knowledge có thể được tổ chức thành một layer riêng ngay trong repository:

repository/
├── AGENTS.md
├── CLAUDE.md
├── .ai/
│   ├── index.md
│   ├── architecture/
│   │   ├── index.md
│   │   ├── system-overview.md
│   │   ├── dependency-rules.md
│   │   └── event-driven-architecture.md
│   ├── services/
│   │   ├── index.md
│   │   ├── agent-service.md
│   │   ├── workflow-service.md
│   │   ├── retrieval-service.md
│   │   └── tool-executor.md
│   ├── standards/
│   │   ├── index.md
│   │   ├── dotnet.md
│   │   ├── python.md
│   │   └── angular.md
│   ├── decisions/
│   │   ├── index.md
│   │   ├── adr-kafka.md
│   │   └── adr-qdrant.md
│   └── runbooks/
│       ├── index.md
│       └── failed-agent-execution.md
├── services/
├── frontend/
└── infrastructure/

Trong ví dụ này, .ai/ được dùng vì tên thư mục thể hiện rõ mục đích. Về bản chất, đây chỉ là một OKF-inspired knowledge bundle; team hoàn toàn có thể gọi nó là knowledge/, docs/architecture/ hoặc một tên khác phù hợp với repository.

Điểm quan trọng không nằm ở tên thư mục. Nó nằm ở việc knowledge được chia thành những concept đủ nhỏ để agent có thể tìm, đọc và đối chiếu theo phạm vi task.

AGENTS.md không còn là nơi chứa toàn bộ sự thật

Sau một thời gian làm việc với Codex và các coding agent khác, tôi nhận ra AGENTS.md hiệu quả nhất khi đóng vai trò bootstrap instruction, không phải knowledge base.

Nó nên nói cho agent biết:

• Phải bắt đầu từ đâu.
• Cách xác định phạm vi ảnh hưởng.
• Khi nào cần đọc architecture document.
• Khi nào cần đọc coding standard.
• Khi nào phải báo conflict.
• Khi nào phải cập nhật lại knowledge sau implementation.

Một phiên bản root instruction có thể ngắn như sau:

## Mandatory knowledge discovery


Before implementation:


1. Read `/.ai/index.md`.
2. Identify the affected service, domain, contract and coding standard.
3. Read only the relevant knowledge documents.
4. Ignore documents with `status: deprecated` except for historical context.
5. Compare documented intent with the current source code.
6. Report material conflicts instead of silently choosing one side.
7. Update affected knowledge documents when architecture, behavior,
   public contracts or operational procedures change.


Do not load the entire `.ai` directory by default.

Cùng một tư duy có thể áp dụng cho CLAUDE.md. File này vẫn là entry point của Claude Code, nhưng không cần chứa toàn bộ kiến trúc. Nó chỉ cần hướng Claude tới knowledge tree và đặt ra quy trình discovery bắt buộc.

Sự phân tách này làm rõ hai loại nội dung vốn thường bị trộn lẫn:

AGENTS.md / CLAUDE.md
    = agent phải làm việc như thế nào


.ai/**/*.md
    = hệ thống được thiết kế như thế nào

Một bên là workflow và guardrail. Bên còn lại là knowledge.

Agent không nên đọc toàn bộ tài liệu trước mỗi task

Trong nhiều implementation plan trước đây, tôi từng viết yêu cầu khá mạnh như “đọc toàn bộ README, AGENTS.md và architecture documents trước khi implement”. Mục tiêu là giảm hallucination và buộc agent tôn trọng thiết kế hiện tại.

Cách này hợp lý khi số tài liệu còn ít. Khi knowledge base lớn hơn, nó lại tạo ra một vấn đề khác: context dilution.

Cách hợp lý hơn là để agent đi qua knowledge theo progressive disclosure:

User requirement
      ↓
AGENTS.md hoặc CLAUDE.md
      ↓
.ai/index.md
      ↓
Index của domain liên quan
      ↓
Một nhóm nhỏ concept cần thiết
      ↓
Source code và test
      ↓
Plan, implementation và validation

Giả sử Codex nhận một task:

Thêm exponential backoff cho Kafka consumer trong Tool Executor, nhưng không được làm lặp lại việc thực thi các tool không idempotent.

Agent không cần đọc toàn bộ kiến trúc của platform. Nó cần một tập context hẹp hơn:

.ai/services/tool-executor.md
.ai/infrastructure/kafka.md
.ai/standards/dotnet.md
.ai/decisions/adr-message-retry.md
.ai/runbooks/kafka-consumer-failure.md

Từ đó, nó mới inspect code thực tế trong services/tool-executor/.

Cách này gần với cách một senior developer xử lý thay đổi: xác định domain bị ảnh hưởng, đọc phần liên quan, kiểm tra implementation hiện tại và quay lại các decision cũ khi có dấu hiệu xung đột. Gần như không ai bắt đầu một thay đổi nhỏ bằng việc đọc lại toàn bộ tài liệu của hệ thống.

Coding agent cũng nên được cung cấp một con đường discovery tương tự.

Một concept document nên chứa gì

Một sai lầm khá phổ biến là viết tài liệu theo kiểu mô tả lại source code: service có những class nào, folder nào chứa repository, controller gọi handler nào. Những tài liệu đó lỗi thời rất nhanh vì code đã thể hiện chúng rõ hơn và chính xác hơn.

Với knowledge layer dành cho coding agent, nên ưu tiên những thông tin mà model khó suy ra chắc chắn chỉ bằng cách đọc code:

• Trách nhiệm chính của service.
• Những việc service không được làm.
• Dependency boundary.
• Invariant của domain.
• Public contract cần giữ ổn định.
• Trade-off đã được chấp nhận.
• Điều kiện cần kiểm tra khi thay đổi.
• Quan hệ với những concept khác.

Một concept cho Tool Executor có thể như sau:

---
type: Service Architecture
title: Tool Executor
description: Executes approved tools and streams execution progress.
status: stable
tags:
  - dotnet
  - kafka
  - tool-execution
verified:
  - by: human:solution-architect
    at: 2026-08-01T09:00:00Z
stale_after: 2026-11-01
---


## Responsibilities


- Execute tools selected by the Agent Service.
- Validate tool permissions before execution.
- Stream execution progress to connected clients.
- Publish execution results through Kafka.


## Architecture constraints


- Must not access the Workflow database directly.
- Must not execute tools outside the approved allow-list.
- Must preserve company and user context across asynchronous messages.
- Retry logic must not duplicate non-idempotent tool execution.


## Dependencies


- [Kafka](../infrastructure/kafka.md)
- [Agent Service](agent-service.md)
- [Tool Permission Policy](../policies/tool-permission.md)


## Validation


- Run unit tests for retry and idempotency behavior.
- Run the integration test against the local Kafka container.

Phần Markdown nói cho engineer và agent biết intent của thiết kế. Phần YAML frontmatter giúp tooling xử lý lifecycle và trust mà không cần đọc toàn bộ body.

Team không cần áp dụng mọi field của OKF ngay từ đầu. Một codebase đang tồn tại có thể bắt đầu chỉ với:

type:
title:
description:
status:

Sau khi quy trình ổn định hơn, team mới bổ sung:

verified:
stale_after:
sources:
resource:

Áp dụng từng bước giúp knowledge layer không biến thành một chương trình documentation lớn nhưng không có người duy trì.

index.md là bản đồ định vị context

Nhiều tài liệu index.md hoặc README cố gắng tóm tắt toàn bộ nội dung bên dưới. Khi file index quá dài, agent lại phải đọc gần như tất cả context ngay từ đầu.

Trong một knowledge tree theo OKF, index.md nên được xem như một bản đồ.

## Architecture


- [System overview](architecture/system-overview.md)
- [Dependency rules](architecture/dependency-rules.md)
- [Event-driven architecture](architecture/event-driven-architecture.md)


## Services


- [Agent Service](services/agent-service.md)
- [Workflow Service](services/workflow-service.md)
- [Tool Executor](services/tool-executor.md)
- [Retrieval Service](services/retrieval-service.md)


## Standards


- [.NET standards](standards/dotnet.md)
- [Python standards](standards/python.md)
- [Angular standards](standards/angular.md)


## Decisions


- [Kafka as the event backbone](decisions/adr-kafka.md)
- [Qdrant for semantic retrieval](decisions/adr-qdrant.md)

Description của mỗi link cần đủ cụ thể để agent route chính xác. Những mô tả chung chung như “thông tin về Tool Executor” gần như không giúp ích. Một mô tả như “tool execution boundary, permission validation, Kafka contract và idempotency rule” mang nhiều tín hiệu hơn.

Ở những domain lớn, mỗi thư mục có thể có một index.md riêng. Agent đi từ root index tới domain index, rồi mới mở concept. Cây knowledge vì thế có thể lớn lên mà không bắt mọi task phải mang toàn bộ tài liệu vào context.

Phân biệt intended architecture và current implementation

Một bài học quan trọng khi dùng coding agent là source code không phải lúc nào cũng đại diện cho thiết kế intended. Nó chủ yếu phản ánh trạng thái implementation hiện tại.

Trong một codebase lâu năm, có thể tồn tại:

• Workaround tạm thời nhưng chưa được gỡ.
• Dependency được thêm để xử lý incident.
• Code legacy vi phạm boundary mới.
• Một refactor mới làm một nửa.
• Tài liệu chưa kịp cập nhật.
• Decision đã thay đổi nhưng ADR chưa được đánh dấu deprecated.

Vì vậy, nguồn sự thật nên được chia thành ba nhóm.

Intended architecture

Knowledge layer mô tả:

• Service được thiết kế để sở hữu trách nhiệm gì.
• Dependency nào được phép.
• Boundary nào phải giữ.
• Business invariant nào không được phá vỡ.

Current implementation

Source code, test và configuration cho biết:

• Hệ thống đang thực sự làm gì.
• Dependency nào đang tồn tại.
• Contract nào đang được publish.
• Behavior nào đã được test.

Historical reasoning

ADR, pull request và Git history giải thích:

• Tại sao một quyết định được đưa ra.
• Trade-off nào đã được chấp nhận.
• Quyết định nào chỉ mang tính tạm thời.
• Bối cảnh nào đã thay đổi.

Nếu knowledge nói Tool Executor không được truy cập Workflow database nhưng source code lại inject WorkflowDbContext, agent không nên âm thầm chọn một bên.

Conflict cần được báo rõ:

Documented intent:
Tool Executor must not access the Workflow database directly.


Observed implementation:
Tool Executor currently references WorkflowDbContext.


Impact:
The current implementation violates the documented service boundary.

Từ đó, task mới có thể được xử lý đúng. Có thể implementation cần được sửa. Cũng có thể architecture đã thay đổi và document cần được cập nhật. Conflict phải được nhìn thấy trước khi agent tạo thêm code dựa trên một giả định chưa được xác nhận.

Knowledge phải thay đổi cùng code

Tài liệu kiến trúc thường rất hữu ích trong giai đoạn design, nhưng nhanh chóng mất giá trị nếu không nằm trong pull request workflow. Code tiếp tục thay đổi, còn tài liệu chỉ được cập nhật khi ai đó nhớ ra.

OKF không tự giải quyết vấn đề này. Đặt Markdown trong Git chỉ làm tài liệu dễ version và review hơn. Team vẫn cần đưa knowledge vào Definition of Done.

Luồng phù hợp cho coding agent là:

Inspect relevant knowledge
          ↓
Inspect current implementation
          ↓
Plan and implement
          ↓
Run tests and validations
          ↓
Evaluate architecture and contract impact
          ↓
Update affected knowledge
          ↓
Review code and knowledge together

Không phải pull request nào cũng cần sửa .ai/. Một refactor nội bộ không thay đổi behavior, boundary hoặc contract có thể không cần cập nhật knowledge.

Knowledge nên được cập nhật khi thay đổi tác động đến:

• Trách nhiệm của service.
• Dependency giữa module hoặc microservice.
• Public API hoặc event contract.
• Business rule.
• Security policy.
• Operational procedure.
• Build, test hoặc deployment workflow.
• Architectural decision.

Theo cách nhìn này, thay đổi Kafka event nhưng không cập nhật contract knowledge cũng giống như thay đổi public API mà không cập nhật OpenAPI specification. Implementation có thể chạy, nhưng engineering artifact chưa hoàn chỉnh.

Status, freshness và verification giúp agent bớt tin nhầm

Một thư mục Markdown không có metadata khiến mọi tài liệu trông có vẻ đáng tin như nhau. Trong thực tế, điều đó hiếm khi đúng.

Trong repository lâu năm, nhiều document vẫn tồn tại dù chỉ còn giá trị lịch sử. Một số file đang là draft; một số khác từng đúng nhưng đã lâu không được kiểm tra lại.

Hai field đơn giản có thể thay đổi cách agent sử dụng knowledge:

status: deprecated
stale_after: 2026-11-01

deprecated nói rằng document không nên được dùng làm thiết kế cho implementation mới. stale_after không khẳng định nội dung sai, nhưng yêu cầu agent đối chiếu lại với source trước khi dựa vào nó.

Phần verified giúp phân biệt tài liệu do agent generate với tài liệu đã được một engineer xác minh:

verified:
  - by: process:architecture-validation
    at: 2026-08-01T07:00:00Z
  - by: human:solution-architect
    at: 2026-08-01T09:00:00Z

Một workflow thực tế có thể đặt policy:

• stable và chưa stale: được sử dụng bình thường.
• draft: chỉ dùng như context tham khảo.
• deprecated: chỉ dùng để hiểu history.
• Stale document: phải so sánh với source code.
• Thay đổi boundary quan trọng: cần human verification.

Metadata không biến tài liệu thành sự thật tuyệt đối. Nó giúp agent biết mức độ thận trọng cần áp dụng.

Instruction file không phải enforcement

Nhiều team có xu hướng viết thêm một câu “must not” vào AGENTS.md mỗi khi agent vi phạm một rule. Cách này có tác dụng nhất định, nhưng chỉ giải quyết phần context.

Nhưng AGENTS.md và CLAUDE.md chỉ là context. Model có thể tuân thủ tốt hơn khi instruction rõ, nhưng đây không phải security boundary hay enforcement mechanism.

Những constraint quan trọng cần được đẩy xuống tooling:

• Architecture test chặn dependency sai.
• Linter chặn coding convention bị vi phạm.
• Schema validation cho Kafka event.
• Pre-commit hook cho format.
• CI check cho broken link và stale concept.
• Permission system cho tool nguy hiểm.
• Sandbox hoặc hook cho những hành động bị cấm.

Ví dụ, rule “Tool Executor không được tham chiếu WorkflowDbContext” nên xuất hiện trong knowledge để agent hiểu design. Đồng thời, một architecture test nên làm build thất bại nếu dependency đó xuất hiện.

Knowledge và enforcement phục vụ hai mục đích khác nhau:

Knowledge giúp agent đưa ra quyết định đúng.
Automation ngăn hệ thống chấp nhận quyết định sai.

Chỉ dùng một trong hai đều chưa đủ cho những boundary quan trọng.

OKF không đồng nghĩa với việc phải thêm vector database

Khi nói về knowledge cho AI, cuộc thảo luận rất dễ chuyển ngay sang embeddings và vector search. Tuy nhiên, đó không phải bước đầu tiên cần làm.

Với vài chục hoặc vài trăm concept, filesystem, index.md, title, description và tags thường đã đủ. Codex hoặc Claude Code có thể dùng search trong repository để tìm concept liên quan.

Vector search chỉ bắt đầu có giá trị khi knowledge base lớn tới mức agent khó định vị đúng tài liệu bằng navigation và lexical search.

Khi đó, OKF file vẫn nên được giữ làm canonical source:

OKF Markdown files
        ↓
Parse metadata và sections
        ↓
Tạo full-text hoặc vector index
        ↓
Search trả về concept ID
        ↓
Mở lại file OKF canonical
        ↓
Kiểm tra status, freshness và verification

Vector database trong kiến trúc này là một derived index. Nó giúp discovery, nhưng không thay thế file trong Git. Nếu index bị rebuild hoặc embedding model thay đổi, knowledge gốc vẫn còn nguyên.

Cách tách này cũng phù hợp với kinh nghiệm xây dựng retrieval pipeline bằng Qdrant: vector store rất hữu ích để tìm nội dung gần nghĩa, nhưng không nên là nơi duy nhất giữ business truth hoặc architecture truth.

Lộ trình áp dụng vào một codebase đang tồn tại

Không nên bắt đầu bằng việc yêu cầu Codex generate hàng trăm file Markdown trong một lần. Kết quả thường rất đầy đủ về hình thức nhưng thiếu độ tin cậy. Agent dễ mô tả lại code, lặp nội dung giữa nhiều file và vô tình biến assumption thành architecture rule.

Cách an toàn hơn là triển khai theo từng giai đoạn.

Giai đoạn 1: Tạo entry point

Bổ sung:

AGENTS.md
CLAUDE.md
.ai/index.md

Hai file instruction cùng trỏ về một discovery workflow. Root index chỉ chứa bản đồ cấp cao.

Giai đoạn 2: Ghi lại những boundary khó suy ra từ code

Nên ưu tiên:

.ai/architecture/system-overview.md
.ai/architecture/dependency-rules.md
.ai/services/<critical-service>.md
.ai/standards/<primary-stack>.md
.ai/decisions/<important-adr>.md

Không cần document mọi class. Phần cần giữ lại là responsibility, invariant, boundary và trade-off.

Giai đoạn 3: Bổ sung metadata và ownership

Khi tree đã ổn định, có thể bổ sung:

type:
description:
status:
verified:
stale_after:

Mỗi concept quan trọng cần một owner hoặc reviewer thực sự. Không có ownership, stale_after chỉ tạo thêm cảnh báo mà không có ai xử lý.

Giai đoạn 4: Đưa knowledge validation vào CI

CI có thể kiểm tra:

• YAML frontmatter hợp lệ.
• Concept có type.
• Link nội bộ không bị hỏng.
• File deprecated không xuất hiện trong active index.
• Concept stale được đưa vào report.
• Public contract change có cập nhật knowledge tương ứng.

Giai đoạn 5: Thêm search khi navigation không còn đủ

Chỉ nên thêm full-text search, graph index hoặc vector search khi đã có dấu hiệu rõ rằng agent không còn tìm đúng concept bằng filesystem. Search layer phải trả về concept ID và metadata, không trở thành một knowledge source độc lập.

Những sai lầm dễ gặp

Biến knowledge layer thành bản sao của source code

Documentation generator có thể tạo ra rất nhiều file mô tả class, method và folder. Nội dung có vẻ đầy đủ nhưng giá trị thấp vì code đã là nguồn tốt hơn.

Knowledge layer nên dành cho intent, boundary, invariant, reasoning và operational constraint.

Generate toàn bộ tài liệu nhưng không review

Agent có thể tạo skeleton nhanh hơn con người, nhưng architecture statement và business rule cần được xác minh. Một rule sai trong .ai/ có thể tiếp tục ảnh hưởng nhiều task sau đó.

Đánh dấu mọi thứ là stable

Nếu mọi concept đều stable, lifecycle metadata chỉ còn là trang trí. Team phải thực sự sử dụng draft, deprecated và stale_after.

Import toàn bộ .ai/ vào mỗi session

Cách này làm mất lợi ích của progressive disclosure. Entry point phải dạy agent cách tìm context, không nạp toàn bộ context ngay từ đầu.

Không cập nhật knowledge trong pull request

Knowledge base chỉ đáng tin khi nó thay đổi cùng code. Khi developer bắt đầu bỏ qua tài liệu vì biết rằng nó đã cũ, coding agent cũng mất đi nguồn context có giá trị nhất.

Sau cùng, vấn đề không nằm ở Markdown

OKF không tự động khiến Codex hay Claude Code trở thành một Solution Architect. Một thư mục .ai/ được tổ chức đẹp cũng không bù được cho architecture yếu, test thiếu hoặc ownership không rõ.

Điều OKF mang lại là một mental model tốt hơn cho context engineering:

• Knowledge được chia thành concept có định danh.
• Agent bắt đầu từ một entry point nhỏ.
• Context được nạp theo phạm vi task.
• Intended architecture được tách khỏi current implementation.
• Tài liệu có trạng thái, freshness và verification.
• Knowledge tham gia vào cùng vòng đời với source code.
• Search index chỉ làm nhiệm vụ discovery.

Ban đầu, tôi cũng tin rằng chỉ cần viết một file instruction thật đầy đủ là đủ cho coding agent. Sau nhiều lần mở rộng codebase, giao task cho agent và xử lý những sai lệch giữa tài liệu với implementation, cách tiếp cận đó cho thấy giới hạn: nó chỉ hoạt động tốt ở giai đoạn đầu.

Khi dự án có nhiều domain, nhiều service và nhiều quyết định không thể suy ra trực tiếp từ code, coding agent cần một knowledge architecture giống như developer cần một software architecture.

OKF không phải đáp án hoàn chỉnh cho toàn bộ bài toán. Nhưng nó cung cấp một nền tảng đủ đơn giản để bắt đầu, đủ có cấu trúc để mở rộng và đủ mở để không khóa team vào một agent hay một vendor cụ thể.

Tài liệu tham khảo

• Google Cloud giới thiệu Open Knowledge Format
• Google Cloud công bố các trust signal trong OKF v0.2
• Open Knowledge Format v0.2 specification
• Open Knowledge Format repository and README
• OpenAI Codex: Custom instructions with AGENTS.md
• OpenAI Codex customization overview
• Claude Code best practices
• Claude Code: How Claude remembers your project