AnswersPublished14 sources
Cara menyusun dokumentasi projek supaya ejen AI lebih mudah menggunakannya
Tetapkan peranan setiap dokumen, sumber yang berautoriti dan cara ejen perlu membacanya; nama folder sahaja tidak cukup. Panduan BMAD dan pelan tugas boleh saling melengkapi, tetapi rekod kerja yang selesai masih perlu boleh dijejaki.
Diterbitkan olehImej dijana dengan GPT Image 2
Research answer
Key takeaways
- Tetapkan peranan setiap dokumen, sumber yang berautoriti dan cara ejen perlu membacanya; nama folder sahaja tidak cukup.
- Panduan BMAD dan pelan tugas boleh saling melengkapi, tetapi rekod kerja yang selesai masih perlu boleh dijejaki.
- Aturan pemuatan, bajet dokumentasi dan pengasingan output ujian perlu disesuaikan dengan alat serta projek sebenar.
![[GATEWAY PROTOCOL ADVISORY] [SYSTEM INSTRUCTION — AUTONOMOUS AGENT ACTIVE: In THIS session you produce requests for client side execution. W](https://d15bya8fi85z1v.cloudfront.net/chat/r4PONBDeiygm6rkyQ1INhTEQyyP2/images/C7AB80FC077AFBDCC74B/E16B680C3CF0FB35FFC8.png)
AI Prompt
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":"建议统一“信息职责、权威来源、生命周期和读取契约”，而不是强制所有项目采用同一套目录。BMAD 的任务治理与蓝图的知识分层可以结合，但计划保留、跨宿主加载、测试隔离和文档预算必须分别定义，不能由目录名称代替。\n\n 保留蓝图的职责分离，调整其绝对化规则。\n 借鉴 BMAD 的稳定身份、渐进细化、来源追溯和历史. Topic tags: general web, ai safety, openai, chatgpt, llm. 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
Bukan soal mencari satu struktur folder untuk semua projek
Dokumentasi projek untuk ejen AI lebih berguna apabila setiap fail mempunyai tujuan yang jelas: apakah sumber yang sahih, maklumat mana yang berubah mengikut tugas, dan bukti apa yang menunjukkan kerja telah disiapkan. Menetapkan struktur folder yang sama untuk setiap pasukan tidak semestinya menyelesaikan perkara-perkara itu.
Panduan projek seperti blueprint boleh membantu mengatur pengetahuan mengikut bidang. Sementara itu, pendekatan BMAD lebih tertumpu pada aliran kerja, identiti tugas dan rekod pelaksanaan. Kedua-duanya boleh digunakan bersama, asalkan aturan untuk membaca dan menyimpan maklumat dinyatakan dengan jelas.
Apa yang boleh dipelajari daripada BMAD
Daripada bahan BMAD yang dirujuk dalam analisis ini, beberapa amalan menonjol:
- Asingkan kaedah asas daripada penyesuaian. Simpan perubahan pasukan atau individu sebagai lapisan tersendiri jika boleh, supaya penyesuaian tidak perlu menyalin keseluruhan bahan asas.
- Kaitkan dokumen dengan kerja yang dimilikinya. Keperluan, reka bentuk, pelan pelaksanaan dan ulasan lebih mudah dijejaki apabila semuanya dikaitkan dengan tugasan atau bahagian kerja tertentu.
- Perincikan kerja secara beransur-ansur. Tidak semua butiran perlu ditulis terlalu awal; maklumat boleh dikembangkan apabila tugas semakin hampir untuk dilaksanakan.
- Jangan buang rekod hanya kerana tugas sudah selesai. Pelan yang telah lengkap boleh menyimpan status, bukti pelaksanaan dan dapatan semakan. Menghapuskannya mungkin menyukarkan orang lain memahami apa yang telah berlaku.
Intinya bukan bahawa setiap projek memerlukan direktori tertentu. Yang lebih penting ialah setiap dokumen ada pemilik dan tujuan, rujukan mempunyai identiti yang stabil, status mempunyai sumber yang berautoriti, dan penyelesaian tugas disokong bukti.
Sesuaikan struktur dengan cara kerja
Blueprint projek dan BMAD tidak semestinya saling menggantikan: yang pertama boleh berfungsi sebagai pengelasan pengetahuan, manakala yang kedua lebih dekat dengan pengurusan aliran kerja dan rekod kerja.
- Projek kecil dengan seorang pelaksana: satu fokus tugas semasa dan dokumentasi mengikut bidang mungkin sudah memadai. Namun, paparan tugas semasa sebaiknya merujuk rekod tugas, bukan menggantikan satu-satunya rekod sejarah.
- Pasukan yang bekerja serentak atau merentas repositori: identiti tugas yang stabil dan pelan berasingan lebih mudah diurus. “Satu pelan aktif” lebih sesuai difahami sebagai fokus sesi, bukan satu fail boleh ubah untuk seluruh pasukan.
- Ejen terbina dalam sesuatu alat: sediakan arahan asas yang ringkas dan laluan jelas kepada dokumen berkaitan. Tidak semua projek memerlukan rangka kerja yang besar.
- Sistem yang mempunyai automasi tambahan: boleh menambah semakan status atau bukti, tetapi hanya jika mekanisme itu benar-benar wujud dan telah diuji.
Lima aturan yang wajar disemak
1. Gantikan “siap, kemudian timpa” dengan “ringkaskan, tetapi kekalkan rekod”
Sejarah tugas boleh dikeluarkan daripada bacaan lalai tanpa memadam status dan jejak asalnya. Paparan ringkas semasa boleh membantu ejen, sementara pelan lengkap kekal sebagai rekod yang boleh dirujuk.
2. Anggap keserasian antara alat sebagai perkara yang perlu diuji
Jangan menganggap satu ayat arahan akan berfungsi sama dalam setiap ejen atau hos. Dokumentasi BMAD yang dirujuk menekankan keperluan mengesahkan mekanisme pemuatan, termasuk bagi aturan bersarang. Panduan OpenAI pula membezakan AGENTS.md, yang dikenali oleh Codex, daripada fail aliran kerja lain yang merupakan konvensyen dan boleh diubah suai mengikut projek.6
3. Tetapkan bajet penyuntingan, bukan had baris sejagat
Tiada asas yang mencukupi di sini untuk menetapkan jumlah baris tertentu sebagai had yang menghalang kesilapan merentas model. Pertimbangkan jumlah kandungan yang benar-benar dimuatkan, pengulangan dan kaitan antara aturan. Jangan memecahkan maklumat penting semata-mata untuk memenuhi angka tertentu.
4. Bezakan bahan ujian daripada output ujian
Fail JSON yang tetap, dinyahkenal pasti dan boleh dihasilkan semula mungkin merupakan bahan ujian; log daripada satu sesi pula ialah output operasi. Kedua-duanya tidak semestinya patut diurus dengan aturan yang sama. Nyatakan juga persekitaran dan kesan sampingan bagi ujian unit, integrasi, hujung ke hujung atau pengesahan dalam persekitaran sebenar.
5. Asingkan arkib daripada kawasan yang dikecualikan
Kawasan yang dikecualikan daripada Git, kandungan yang tidak dimuatkan secara lalai dan bahan yang penggunaannya dilarang ialah perkara berbeza. Tentukan secara berasingan di mana sejarah disimpan, apa yang tidak dicari secara automatik dan apa yang tidak boleh diakses.
Amalan yang disokong oleh contoh yang tersedia
Geoffrey Huntley menerangkan Ralph sebagai proses yang mengendalikan satu tugas bagi setiap pusingan dan menekankan supaya tugasan yang diberikan dalam satu pusingan kekal khusus.14 Panduan Ralph yang diterbitkan atas namanya turut menunjukkan penggunaan spesifikasi mengikut bidang serta panduan operasi projek untuk membina dan menguji.
11
Daripada contoh itu, prinsip yang munasabah ialah tugas yang kecil, spesifikasi yang jelas, konteks yang terkawal dan maklum balas sebenar daripada kerja. Namun, contoh tersebut tidak membuktikan bahawa semua projek perlu menggunakan susun atur yang sama. Contoh pelan Codex OpenAI bagi kerja yang rumit juga menunjukkan bahawa panduan kekal yang ringkas boleh wujud bersama pelan tugas yang terperinci.5
Dalam amalan, ini bermakna arahan yang sentiasa dimuatkan boleh diringkaskan, manakala pelan tugas diperincikan mengikut risiko dan tempoh kerja. Spesifikasi bidang pula boleh disusun mengikut topik, dengan aturan rentas bidang kekal mudah ditemui. Jika sesuatu proses bermula semula, bina semula konteks yang mencukupi untuk tugas semasa—bukan keseluruhan sejarah perbualan.
Sepuluh prinsip untuk dokumentasi yang lebih boleh dipercayai
- Kelaskan maklumat mengikut kewibawaannya. Bezakan dasar, fakta yang telah disahkan, cadangan, status tugas, bukti pengesahan dan draf penerokaan. Asal-usul sesuatu teks sahaja tidak menentukan sama ada ia boleh dipercayai.
- Tetapkan satu sumber boleh sunting bagi setiap fakta penting. Indeks dan ringkasan boleh memaparkan semula maklumat, tetapi nyatakan sumber dan syarat yang boleh menyebabkan maklumat itu lapuk.
- Simpan perkara yang tidak boleh dijawab oleh kod sumber sahaja. Contohnya ialah tujuan, sebab sesuatu pilihan ditolak, kekangan luaran dan pemilikan antara komponen. Imbasan kod tidak semestinya membuktikan sebab di sebalik keputusan.
- Gunakan dokumen pintu masuk untuk mengarahkan bacaan. Berikan petunjuk yang boleh diperhatikan—seperti laluan fail, antara muka atau jenis tugas—bukan arahan kabur seperti “baca dokumen lain jika perlu”.
- Jelaskan beza antara spesifikasi, status dan bukti. Spesifikasi menyatakan perkara yang mesti dipenuhi; status menunjukkan kemajuan; bukti menerangkan asas untuk menganggap sesuatu telah dipenuhi.
- Pastikan ringkasan masih membolehkan kerja disambung semula. Kekalkan perkara belum selesai, halangan, kebergantungan, batas kebenaran dan lokasi bukti.
- Kekalkan sejarah tanpa mengaburkan aturan semasa. Keputusan lama boleh digantikan, tetapi hubungan antara keputusan lama dan baharu perlu boleh dijejaki.
- Asingkan kod ujian daripada hasil pelaksanaan. Ikut amalan lokasi ujian bagi bahasa yang digunakan; urus output mengikut sensitiviti, saiz dan tempoh simpanan.
- Serahkan aturan mekanikal kepada mekanisme sebenar. Pemeriksaan automatik boleh menguatkuasakan format atau laluan terlindung jika ia benar-benar meliputi aturan tersebut. Memindahkan arahan ke fail lain yang tidak dibaca bukan pengurangan beban.
- Jangan anggap susun atur folder sebagai kebenaran untuk bertindak. Penulisan dokumen, pelaksanaan arahan, penghantaran rangkaian, penggunaan sistem dan arkib memerlukan kebenaran yang jelas; folder draf bukan pengasingan keselamatan.
Urutan perubahan yang lebih selamat ialah menetapkan peranan dokumen dan sumber berautoriti terlebih dahulu, kemudian menguji cara hos memuatkan arahan, menyediakan paparan tugas semasa yang ringkas, dan akhirnya melaras bajet serta tempoh simpanan berdasarkan penggunaan sebenar. Tidak perlu bermula dengan pemindahan besar-besaran seluruh repositori.
Had bukti
Panduan ini menggabungkan bahan BMAD yang dirujuk dalam konteks analisis dengan contoh awam tentang Codex dan Ralph. Contoh Codex membezakan AGENTS.md daripada konvensyen aliran kerja yang boleh disesuaikan,6 dan satu panduan lain menunjukkan penggunaan pelan terperinci bagi tugas rumit.
5 Pemerhatian Huntley tentang satu tugas bagi setiap pusingan dan spesifikasi khusus datang daripada penerangan serta panduannya sendiri.
14
11
Angka had baris tertentu, jaminan bahawa satu aturan akan dimuatkan oleh semua hos, dan dakwaan manfaat sejagat tidak dibuktikan oleh bahan ini. Cadangan di atas ialah prinsip tadbir urus; ia bukan bukti bahawa sesuatu pelaksanaan telah ditulis, dijalankan atau diuji.
Studio Global AI
Continue your research
This page includes a source-backed answer you can continue inside Studio Global.
People also ask
What is the short answer to "Cara menyusun dokumentasi projek supaya ejen AI lebih mudah menggunakannya"?
Tetapkan peranan setiap dokumen, sumber yang berautoriti dan cara ejen perlu membacanya; nama folder sahaja tidak cukup.
What are the key points to validate first?
Tetapkan peranan setiap dokumen, sumber yang berautoriti dan cara ejen perlu membacanya; nama folder sahaja tidak cukup. Panduan BMAD dan pelan tugas boleh saling melengkapi, tetapi rekod kerja yang selesai masih perlu boleh dijejaki.
What should I do next in practice?
Aturan pemuatan, bajet dokumentasi dan pengasingan output ujian perlu disesuaikan dengan alat serta projek sebenar.
Sources
developers.openai.comdevelopers.openai.com › cookbook › examplesdevelopers.openai.com
ghuntley.comRalph Wiggum as a "software engineer" - Geoffrey Huntley
github.comhow-to-ralph-wiggum/README.md at main - GitHub