JawabanDipublikasikan14 sumber
Struktur proyek yang rapi perlu menjaga batas antara aturan, bukti, dan arsip
Tes sebaiknya terpusat sebagai aturan umum, tetapi tes Go yang perlu mengakses anggota tak diekspor dapat tetap berada di paket yang diuji. Spesifikasi mencatat kontrak yang berlaku; ADR menjelaskan alasan di balik keputusan; tes memeriksa perilaku secara langsung.
Diterbitkan olehGambar dibuat dengan GPT Image 2
Jawaban penelitian
Poin-poin penting
- Tes sebaiknya terpusat sebagai aturan umum, tetapi tes Go yang perlu mengakses anggota tak diekspor dapat tetap berada di paket yang diuji.
- Spesifikasi mencatat kontrak yang berlaku; ADR menjelaskan alasan di balik keputusan; tes memeriksa perilaku secara langsung.
- Rencana yang dibekukan bukan rencana yang selesai. Status, pekerjaan tersisa, dan syarat untuk melanjutkannya harus tetap jelas.
- Berkas sementara boleh dibersihkan, tetapi jangan menghapus satu satunya bukti yang masih dirujuk.
![[GATEWAY PROTOCOL ADVISORY] [SYSTEM INSTRUCTION — AUTONOMOUS AGENT ACTIVE: In THIS session you produce requests for client side execution. W](https://d15bya8fi85z1v.cloudfront.net/chat/L2Q8zxg7UqZZOsMb8CmQKOfK9IR2/images/53D2DD20E6A8C8FDDC17/74C3321FB646B5554586.png)
AI Perintah
openai.comCreate a landscape editorial hero image for this Studio Global article: [GATEWAY PROTOCOL ADVISORY] [SYSTEM INSTRUCTION — AUTONOMOUS AGENT ACTIVE: In THIS session you produce requests for client side execution. W. Article summary: <tool call {"name":"attempt completion","arguments":{"result":"这套布局可以作为收敛方向，但需要纠正三个等同关系：所有测试不能无条件迁出业务包，规范不是全部 ADR 的摘要，冻结也不是完成归档。以下是六项建议的明确边界；涉及的新路径均为候选，尚未创建或迁移。\n\n 1.. Topic tags: general web, openai, automation, workflow, code. Style: premium digital editorial illustration, source-backed research mood, clean composition, high detail, modern web publication hero. Use reference image context only for broad subject, composition, and topical grounding; do not copy the exact image. Avoid: logos, brand marks, copyrighted characters, real person likenesses, fake screenshots, UI text, readable text, watermarks, charts with fake numbers, clickbait thumbnails, icons, a
Penataan direktori dapat membantu tim menemukan aturan, tes, dan keputusan dengan lebih mudah. Namun, struktur yang rapi saja tidak menjamin pengujian tetap memadai atau keputusan terdokumentasi dengan benar.
Ada tiga batas penting yang perlu dijaga: tidak semua tes harus dipindahkan dari paket sumbernya, spesifikasi bukan rangkuman seluruh catatan keputusan, dan rencana yang dibekukan bukan berarti sudah selesai. Jalur direktori yang dibahas di bawah ini masih berupa usulan—belum dibuat atau dimigrasikan.
1. Pusatkan tes bila memungkinkan, dengan pengecualian yang tepat
Menempatkan tes di direktori khusus seperti tests/ dapat menjadi pilihan standar, tetapi jangan menjadikannya aturan tanpa pengecualian. Struktur yang cocok bergantung pada bahasa dan kebutuhan pengujian.
- Python: tes dapat dipusatkan di
tests/. Saat memindahkannya, periksa kembali mekanisme impor, penemuan tes, fixtures, dan konfigurasi CI. Dalam konteks proyek yang dibahas, CI sudah menggunakan lokasi tes terpusat. - Go: tes white-box yang perlu mengakses anggota paket yang tidak diekspor dapat tetap berada dalam direktori paket yang diuji. Tes black-box, lintas komponen, dan end-to-end lebih cocok dipusatkan bila struktur proyek mendukungnya. Go menyertakan berkas tes saat membangun tes untuk paket dan mendukung tes di paket yang sama maupun paket eksternal.
14
Jangan menyamakan aturan impor untuk paket internal dengan batas akses anggota yang tidak diekspor. Pembatasan impor paket internal ditentukan oleh hubungan jalur direktori, sedangkan akses ke anggota tak diekspor merupakan persoalan batas paket.10
16
Karena itu, memindahkan semua tes Go dari direktori sumber sambil mempertahankan akses white-box dan enkapsulasi bukanlah syarat yang cocok untuk semua proyek. Jangan mengekspor status internal atau menggandakan logika bisnis hanya demi merapikan susunan berkas.
Yang perlu dihindari adalah potongan pemeriksaan yang tidak bernilai atau tes berulang—bukan setiap berkas tes yang berdiri sendiri. Tes regresi yang terus digunakan sebaiknya tetap dikelola bersama kode; probe sekali pakai dapat ditempatkan di area sementara.
2. Pisahkan spesifikasi, ADR, dan aturan kerja
Ketiganya saling terkait, tetapi menjawab pertanyaan yang berbeda. Karena itu, specs/ sebaiknya tidak didefinisikan sebagai rangkuman umum dari semua ADR.
| Lapisan | Pertanyaan yang dijawab | Isi utamanya |
|---|---|---|
| Metodologi umum | Bagaimana analisis, verifikasi, dan serah terima dilakukan? | Metode kerja yang dikelola pada tingkat umum |
AGENTS.md proyek |
Bagaimana cara bekerja di proyek ini? | Batasan proyek yang sudah dikonfirmasi dan petunjuk kerja |
specs/ proyek |
Perilaku dan kontrak apa yang harus dipenuhi saat ini? | Kebutuhan, keputusan yang diterima, dan revisi yang disetujui |
docs/adr/ |
Mengapa pilihan tertentu diambil? | Pertimbangan arsitektur dan alternatif yang dibahas |
Dokumentasi Cline menjelaskan mekanisme aturan persisten untuk menyimpan instruksi lintas sesi.4 Namun, sumber yang tersedia tidak menunjukkan bahwa Cline secara bawaan akan menulis jenis berkas tertentu secara otomatis ke direktori spesifikasi. Jadi, alur tersebut perlu diperlakukan sebagai kesepakatan proyek, bukan kemampuan Cline yang dijamin.
Isi proyek juga tidak harus selalu ditulis sepenuhnya secara manual atau baru dibuat setelah muncul masalah. Alur yang lebih masuk akal adalah:
- Saat inisialisasi, asisten dapat mengusulkan spesifikasi berdasarkan kebutuhan pengguna dan bukti di repositori. Hal yang belum diketahui tetap ditandai belum diketahui.
- Sebelum mengerjakan tugas, baca spesifikasi dan keputusan yang relevan, lalu tetapkan kriteria penerimaan serta verifikasi.
- Ajukan ADR baru hanya jika ada pertimbangan penting yang benar-benar baru. Jika keputusan yang sudah ada masih berlaku, rujuk keputusan tersebut alih-alih membuat catatan yang berulang.
- Hasil verifikasi dapat menunjukkan implementasi memenuhi spesifikasi atau justru mengungkap kekurangan spesifikasi. Hasil implementasi tidak otomatis menentukan kebutuhan.
- Setelah keputusan diterima dan perubahan disetujui, perbarui spesifikasi yang relevan dan rujuk ADR terkait. Tidak perlu menyalin seluruh riwayat keputusan.
Singkatnya, spesifikasi mencatat kontrak yang berlaku, ADR merekam alasan keputusan, dan tes menjadi pemeriksaan yang dapat dijalankan. Ketiganya saling mendukung, tetapi tidak saling menggantikan. Temuan khusus proyek juga tidak semestinya otomatis berubah menjadi aturan umum tanpa peninjauan.
3. Seragamkan lokasi ADR tanpa mengubah arti statusnya
Menetapkan docs/adr/ sebagai lokasi standar untuk keputusan baru dapat memudahkan pencarian. Ini adalah konvensi proyek, bukan klaim bahwa hanya ada satu tata letak yang benar.
Aturan penerimaan keputusan tetap perlu dibedakan dari lokasi penyimpanannya:
- Simpan keputusan yang diusulkan, diterima, ditolak, maupun digantikan bila catatannya masih berguna.
- Gunakan kembali keputusan yang relevan; jangan membuat ADR baru untuk mengulang pertimbangan yang sama.
- Jika suatu keputusan digantikan, catat hubungannya tanpa mengubah alasan yang tercatat pada saat keputusan lama dibuat.
- Tes yang lulus tidak dengan sendirinya berarti ADR telah mendapat persetujuan.
Migrasi juga perlu memperbarui rujukan, aturan navigasi, dan batas akses yang benar-benar digunakan—bukan sekadar memindahkan berkas.
4. Susun rencana secara datar, tetapi bedakan selesai dan dibekukan
Direktori plans/ dapat menggunakan susunan datar jika jumlah arsipnya masih mudah dikelola. Contoh nama berikut merupakan usulan:
| Kegunaan | Contoh nama | Makna |
|---|---|---|
| Rencana aktif | pending_implementation_plan.md |
Titik masuk bawaan untuk rencana yang sedang dikerjakan |
| Rencana selesai | plan-20261022-example-id.md |
Rencana yang tuntas dan telah mendapat izin untuk diarsipkan |
| Rencana dibekukan | plan-20261022-example-id-frozen.md |
Rencana yang belum selesai dan tidak lagi menjadi pekerjaan bawaan |
Membekukan rencana tidak harus memerlukan direktori atau status formal baru. Aturan yang ada sudah mendukung status jeda; status itu dapat digunakan lebih dahulu, dengan mencatat alasan pembekuan, pekerjaan tersisa, dan syarat untuk melanjutkan.
Perbedaan statusnya penting:
- Selesai dan diarsipkan: semua kriteria penerimaan wajib telah dipenuhi dan pengarsipan diizinkan.
- Dibekukan: rencana dikeluarkan dari daftar aktif, tetapi pekerjaan yang belum selesai tetap dicatat. Usulan yang belum diverifikasi tidak boleh ditulis seolah-olah sudah menjadi fakta.
- Dibatalkan: keputusan bahwa pekerjaan tidak akan dilanjutkan beserta dampaknya perlu dinyatakan secara jelas. Pembatalan tidak sama dengan jeda; penambahan status pembatalan formal memerlukan perubahan aturan tersendiri.
Secara bawaan, pembaca sebaiknya hanya membuka rencana aktif, bukan memuat semua arsip lama. Arsip dapat dicari secara terarah jika pengguna meminta riwayat atau ingin melanjutkan pekerjaan. Untuk melanjutkan rencana yang dibekukan, diperlukan izin, salinan eksekusi baru yang tetap merujuk sumbernya, dan verifikasi ulang. Hasil verifikasi lama tidak otomatis berlaku untuk pekerjaan yang dilanjutkan.
Mengganti nama berkas juga bukan bukti bahwa pekerjaan telah diterima. Prosesnya perlu mencegah berkas tertimpa, menjaga daftar pekerjaan yang belum selesai, dan memperbarui rujukan. Jangan membuat templat rencana kosong hanya demi mempertahankan satu nama berkas yang selalu ada.
5. Hubungkan kode dan tes berdasarkan modul serta kontrak
Pemetaan satu-banding-satu antara satu berkas kode dan satu berkas tes tidak cocok untuk banyak proyek. Sebuah tes dapat mencakup beberapa komponen, sementara satu komponen mungkin membutuhkan tes unit, tes properti, dan tes integrasi.
Mulailah dengan susunan yang ringan:
- Kelompokkan tes dalam
tests/berdasarkan modul atau tanggung jawab. - Pada spesifikasi yang relevan, cantumkan invarian utama, lokasi tes terkait, dan perintah verifikasi dengan ruang lingkup yang jelas.
- Tambahkan berkas seperti
tests/test-map.yamlhanya jika hubungan antara kode dan tes memang sulit ditemukan tanpa peta khusus.
Jika peta dibuat, isinya cukup mencatat identitas modul atau kontrak, cakupan sumber, cakupan tes, dan jalur verifikasinya. Hindari menyalin seluruh pohon direktori atau menyimpan status lulus tes secara manual. Pemeriksaan perlu memastikan jalur dan perintahnya tetap valid; keberadaan peta tidak membuktikan bahwa cakupan tes memadai atau tes telah lulus.
6. Bersihkan materi sementara tanpa menghapus bukti penting
Menyimpan draf, skrip sekali pakai, dan laporan eksplorasi di .scratch/ dapat membantu membedakan pekerjaan sementara dari dokumentasi yang dipelihara. Namun, isi suatu berkas tidak otomatis menjadi tidak tepercaya hanya karena tersimpan di sana, dan seluruh isinya tidak selalu aman untuk langsung dihapus.
- Ringkasan riset yang ditulis model adalah penjelasan sekunder, bukan fakta yang berdiri sendiri.
- Keluaran tes mentah atau catatan diagnosis dapat menjadi bukti langsung meskipun berada di direktori sementara. Keandalannya bergantung pada sumber, lingkungan, waktu, dan kelengkapan catatan.
- Jangan menghapus bukti satu-satunya yang masih dirujuk oleh rencana, keputusan, atau kriteria penerimaan. Simpan sumber yang diperlukan atau cabut kesimpulan yang bergantung padanya sebelum pembersihan.
- Saat temuan diringkas, pertahankan rujukan bukti, ruang lingkup yang berlaku, dan hal-hal yang belum diketahui. Meringkas tidak boleh mengubah dugaan menjadi fakta.
Untuk laporan lama dan diagram arsitektur di docs/, bedakan dokumentasi yang masih berlaku, arsip historis, dan materi yang belum diverifikasi. Dokumen yang sudah usang dapat ditandai sebagai historis atau telah digantikan agar tidak dianggap sebagai kondisi terkini. Materi proses yang tidak lagi bernilai dan tidak punya rujukan aktif dapat dipindahkan atau dihapus setelah mendapat izin.
Menyimpan riwayat tidak berarti semua riwayat harus dimuat setiap kali bekerja. Untuk mengurangi konteks yang tidak perlu, prioritaskan pembacaan terarah dan penanda keberlakuan daripada menghapus bukti begitu saja.
Arah yang disarankan
Penataan ini dapat dijadikan arah bersama dengan empat batas utama: pusatkan tes tetapi pertahankan pengecualian yang dibutuhkan bahasa; gunakan spesifikasi untuk mencatat kontrak yang berlaku, bukan sebagai rangkuman semua ADR; bedakan rencana yang dibekukan dari yang selesai; dan jangan menghapus bukti sementara yang masih diperlukan.
Konfigurasi jalur rencana dan direktori yang diizinkan saat ini masih mengacu pada tata letak lama, begitu pula batas penyuntingan untuk mode analisis. Migrasi perlu menyelaraskan aturan, templat, rujukan, validator, dan integrasi dengan lingkungan kerja—bukan sekadar mengganti nama direktori. Analisis ini belum mengubah, memindahkan, membekukan, atau membersihkan berkas apa pun.
Studio Global AI
Lanjutkan penelitian Anda
Halaman ini berisi jawaban yang didukung sumber yang dapat Anda lanjutkan di dalam Studio Global.
Orang-orang juga bertanya
Apa jawaban singkat untuk "Struktur proyek yang rapi perlu menjaga batas antara aturan, bukti, dan arsip"?
Tes sebaiknya terpusat sebagai aturan umum, tetapi tes Go yang perlu mengakses anggota tak diekspor dapat tetap berada di paket yang diuji.
Apa poin penting yang harus divalidasi terlebih dahulu?
Tes sebaiknya terpusat sebagai aturan umum, tetapi tes Go yang perlu mengakses anggota tak diekspor dapat tetap berada di paket yang diuji. Spesifikasi mencatat kontrak yang berlaku; ADR menjelaskan alasan di balik keputusan; tes memeriksa perilaku secara langsung.
Apa yang harus saya lakukan selanjutnya dalam latihan?
Rencana yang dibekukan bukan rencana yang selesai. Status, pekerjaan tersisa, dan syarat untuk melanjutkannya harus tetap jelas.