Make Context Discoverable
Membuat aturan repo, ADR, test, dan convention mudah ditemukan tanpa mengandalkan agent untuk menebak.
Failure pattern
Coding agent sering salah bukan karena tidak mencari context, tetapi karena menemukan context yang salah lebih dulu. Ia membaca ADR lama, pattern legacy, atau test yang tidak lagi authoritative.
Repo besar punya banyak kebenaran yang pernah benar. Harness harus membantu agent menemukan kebenaran yang masih berlaku.
Incident: Invite model yang sudah superseded
Agent memperbaiki invite flow dengan menulis ke tabel workspace_invites karena melihat file legacy dan test lama. Padahal ADR terbaru menyatakan invite acceptance sekarang berbasis membership_events.
Patch-nya compile, tetapi melawan arsitektur sekarang.
Harness principle
Make context discoverable berarti repo punya context ladder. Agent mulai dari task brief, lalu context index, lalu source authoritative, lalu file pendukung. Bukan “search everything.”
Untuk coding agent, authority sering berurutan seperti ini: current issue, ADR terbaru, architecture doc aktif, tests yang relevan, lalu legacy notes.
Operating practice
Gunakan context decision log:
| Question | Source | Decision |
|---|---|---|
| Invite model aktif? | ADR-029 | pakai membership_events |
| Legacy table masih ditulis? | legacy note | read-only compatibility |
| Test mana yang authoritative? | invite e2e | tambah regression di sana |
| Route utama? | /invite/:token | patch dimulai dari sini |
Log ini kecil, tetapi membuat pilihan context terlihat.
Coding-agent example
Agent menulis:
Used ADR-029 because it supersedes ADR-014.
Ignored legacy invite helper for new writes.
Added regression to current invite acceptance e2e.Reviewer langsung tahu apakah agent berdiri di context yang benar.
Common mistakes
Kesalahan pertama adalah berkata “read the docs” tanpa hierarchy. Kesalahan kedua adalah memasukkan terlalu banyak file ke prompt sampai agent tidak tahu mana yang current.
Kesalahan ketiga adalah tidak mencatat source yang dipakai. Tanpa itu, stale context sulit dideteksi.
Practical exercise
Buat context ladder untuk satu area repo: auth, billing, onboarding, atau migration. Tandai source authoritative, legacy, dan supporting.
Key takeaways
- Context discoverability adalah masalah authority, bukan volume.
- Agent harus mencatat source yang dipakai.
- Legacy context perlu label agar tidak dipakai sebagai rule baru.