Dari AI Blueprint Project ZIP ke Code

AI Blueprint Project ZIP adalah handoff package untuk memulai implementation dengan coding agent. Isi setiap ZIP dapat berbeda berdasarkan project dan versi generator, jadi gunakan manifest, implementation guide, dan file yang ada sebagai source of truth-bukan asumsi dari nama file saja.

Project ZIP hanya tersedia setelah Blueprint penuh selesai direview dan mendapat approval final. Free preview biasa berhenti di App Map dalam mode hanya-baca dan tidak menyediakan AI Assistant atau download. Baca Free Tier, Revisi AI Assistant, dan Project ZIP sebelum mengikuti tutorial implementasi ini.

Contoh ZIP dapat berisi:

docs/
.env.local
AGENT.md
AGENTS.md
AI_CODING_AGENT_IMPLEMENTATION_GUIDE_FOR_USERS.md
Blueprint-PRD-<Project>.md
Complete-Database-Schema.md
manifest.json
PROMPT_1.md
PROMPT_2.md
PROMPT_3.md
PROMPT_4.md
PROMPT_5.md
UI-MOCKUP-DIRECTION-SUMMARY-<Project>.md

Nama dan jumlah file dapat berbeda. Nama file project-specific mengikuti judul Blueprint. manifest.json adalah indeks yang memastikan Anda tidak menebak nama atau peran file.

Peta Isi Project ZIP dan Fungsi Setiap File

File kontrol dan petunjuk kerja

File requirement dan keputusan

Lima prompt implementation

PROMPT_3.md bukan tombol "selesaikan semuanya". Jalankan untuk satu vertical slice, verifikasi, commit, lalu ulangi untuk slice berikutnya.

Aturan Source of Truth ketika File Terlihat Berbeda

Gunakan urutan keputusan berikut:

1. manifest.json menentukan file apa yang termasuk package dan versi artifact.
2. Blueprint PRD menentukan scope dan requirement implementation yang disetujui.
3. Complete-Database-Schema.md menentukan bentuk persistence dan migration.
4. Dokumen individual di docs/ memberi detail domain dan traceability.
5. Human PRD membantu review manusia, tetapi tidak boleh diam-diam mengubah requirement.
6. UI Mockup Direction menentukan art direction, bukan business rule.
7. Implementation guide dan PROMPT_1...5 menentukan cara kerja, bukan menambah fitur produk.

Jika dua authority benar-benar bertentangan, agent harus berhenti, menunjukkan dua kutipan singkat beserta nama file, menjelaskan dampaknya, dan meminta keputusan. Jangan memilih diam-diam.

Step 0 - Extract ZIP Dulu

Jangan coding langsung di dalam compressed ZIP.

Di Windows, gunakan Extract all. Setelah extraction, buka folder hasil extract sebagai project folder.

Kenapa penting?

• Git bekerja pada folder nyata;
• agent perlu membaca/menulis file normal;
• command build/install membutuhkan filesystem biasa;
• perubahan harus dapat di-diff dan di-commit.

Step 1 - Cek Secret Sebelum Git

Jika ada .env.local, buka dan pastikan:

• tidak ada production secret yang tidak perlu;
• file tersebut masuk .gitignore;
• jangan publish value secret ke chat/prompt;
• buat .env.example dengan nama variable tanpa nilai sensitif bila dibutuhkan.

Contoh:

# .gitignore
.env
.env.local
.env.*.local

Contoh .env.example:

DATABASE_URL=
AUTH_SECRET=
NEXT_PUBLIC_APP_URL=http://localhost:3000

Step 2 - Buat Git Baseline

Jika folder belum Git repository:

git init
git add .
git commit -m "chore: import AI Blueprint handoff"

Jika sudah Git repository:

git status
git add .
git commit -m "chore: checkpoint before AI implementation"

Jangan re-init repository existing.

Step 3 - Baca Source of Truth Sebelum Coding

Urutan aman:

1. manifest.json bila ada.
2. AI_CODING_AGENT_IMPLEMENTATION_GUIDE_FOR_USERS.md bila ada.
3. AGENTS.md / AGENT.md bila ada.
4. Blueprint PRD.
5. Database schema.
6. docs/.
7. PROMPT_1...N sesuai urutan yang didefinisikan manifest/guide.

Jangan berasumsi AGENT.md dan AGENTS.md mempunyai arti auto-read yang sama di semua tool. Agent behavior berbeda. Pastikan file penting secara eksplisit diminta untuk dibaca.

Render dokumen dan inspeksi file data

Anda dapat membuka dokumen .md di FileMira Markdown Viewer untuk melihat source dan hasil render berdampingan. Untuk isi ZIP lain, gunakan viewer yang sesuai:

• manifest.json atau file .json: JSON Viewer;
• data .csv: CSV Editor;
• konfigurasi .yaml/.yml: YAML Viewer;
• konfigurasi .toml: TOML Viewer.

FileMira menyatakan file diproses lokal di browser. Tetap buka .env.local sebagai plain text hanya di perangkat Anda, jangan unggah atau tempel secret ke viewer, chat, issue, atau screenshot.

Step 4 - Pilih Agent

Pilih satu:

• Codex/ChatGPT coding surface;
• Claude Code;
• Gemini CLI;
• OpenCode;
• ZCode/GLM path;
• Kimi Code;
• atau coding tool lain yang dapat membaca repository.

Untuk pemula, gunakan satu main agent pada satu working tree.

Step 5 - Jalankan PROMPT_1.md dan Minta Pemahaman Lengkap

Jangan langsung berkata "buat aplikasi ini sampai selesai". Buka PROMPT_1.md, gunakan isinya utuh, lalu tambahkan lokasi folder project jika tool membutuhkannya. Prompt 1 harus membuat agent membaca PRD dua kali secara teliti sebelum edit.

Gunakan prompt:

Baca manifest, implementation guide, PRD, database schema, docs, dan AGENTS/AGENT jika ada. Ikuti PROMPT_1.md sebagai workflow utama.
Read PRD once for product meaning, then read it a second time for requirements, dependencies, and acceptance criteria.
Jangan ubah file apa pun.

Buat PLAN.md yang menjelaskan:
- source of truth dan conflict yang ditemukan;
- urutan implementasi;
- file/area yang kemungkinan berubah;
- dependency dan command yang diperlukan;
- risiko dan security boundary;
- acceptance criteria per stage;
- command verifikasi;
- informasi yang masih hilang.

Pada akhir jawaban, jelaskan kembali seluruh project: tujuan, aktor, workflow, fitur, data, permission, integrasi, UI direction, non-goals, risiko, dan definisi selesai.
Jangan membuat asumsi produk baru jika dokumen tidak menjelaskannya.

Review plan sebagai manusia. Cocokkan daftar fitur agent dengan PRD. Jika ada requirement yang hilang, jangan lanjut ke prototype.

Step 6 - Setup Project Mengikuti Technical Foundation/Guide

Jika ZIP hanya dokumentasi dan belum ada source code, agent mungkin perlu membuat project skeleton sesuai Technical Foundation. Jangan membiarkan agent mengganti stack karena preference-nya sendiri.

Contoh rule:

Gunakan stack yang didefinisikan Technical Foundation/implementation guide.
Jangan mengganti framework, database, auth, atau package manager tanpa alasan teknis yang terdokumentasi dan approval.

Setelah scaffold:

npm install
npm run dev

Command sebenarnya bergantung pada stack.

Buat checkpoint:

git add .
git commit -m "chore: scaffold project from blueprint"

Step 7 - Design Gate Sebelum Frontend Besar

Sebelum agent membuat banyak screen:

1. User memberi 2-3 mockup/reference images.
2. Jika belum ada, user dapat mencari inspiration dari getdesign.md, Aura, shadcn.io, shadcn/ui, Magic UI, Mobbin/Page Flows, atau sumber lain yang legal digunakan sebagai reference.
3. Alternatif: minta AI dengan image-generation capability membuat 2-3 mockup dari ringkasan PRD.
4. Pilih satu direction.
5. Buat DESIGN.md.
6. Buat asset inventory/ASSETS.md.
7. Baru implement satu vertical slice.

Minimum reference set

Untuk SaaS/web app:

01-landing-reference.png
02-dashboard-reference.png
03-mobile-reference.png

Untuk app tanpa landing:

01-main-workspace.png
02-detail-form.png
03-mobile.png

References bukan asset production. Jangan commit copyrighted screenshot sebagai production content bila tidak memiliki hak.

Step 8 - Buat DESIGN.md

Gunakan templates/DESIGN-template.md dari paket Learning atau buat file baru di project. Untuk inventory asset, tersedia juga templates/ASSETS-template.md.

Minimal isi:

• visual direction;
• references dan trait yang dipinjam;
• typography;
• color roles;
• spacing/grid;
• layout rules;
• component rules;
• states;
• responsive;
• accessibility;
• motion;
• asset rules;
• do/don't;
• visual QA.

Prompt:

Baca PRD dan tiga reference images.
Jangan implement UI dulu.
Buat DESIGN.md yang mengekstrak visual rules tanpa menyalin brand/copy/assets pihak lain.
Tandai keputusan yang tidak dapat disimpulkan dari reference sebagai open decision.

Review DESIGN.md, baru izinkan implementasi.

Step 9 - Jalankan Blueprint Prompt Secara Bertahap

Jika ZIP memiliki PROMPT_1.md sampai PROMPT_5.md, jangan paste semuanya sekaligus.

Gunakan manifest/guide untuk menentukan urutan dan arti masing-masing prompt.

Loop per stage:

READ STAGE
→ PLAN
→ IMPLEMENT
→ LINT/TYPECHECK/TEST/BUILD
→ UI SCREENSHOT/VERIFY bila perlu
→ GIT DIFF
→ HUMAN REVIEW
→ COMMIT
→ NEXT STAGE

Prompt 2: prototype yang benar-benar dapat dicoba

Prototype tidak cukup berupa screen statis. Minimum acceptance:

• semua route utama dapat dibuka;
• navigasi dan tombol penting bekerja;
• satu alur end-to-end dapat diselesaikan;
• create, read, update, dan delete sederhana memakai dummy data;
• form mempunyai validation dan feedback;
• loading, empty, error, success, disabled, dan responsive state tersedia;
• tidak ada tombol palsu tanpa penjelasan;
• data dummy terpisah dari kontrak production.

Prompt 3: production per vertical slice

Pilih satu outcome user, bukan satu layer teknis. Contoh slice "membuat appointment" meliputi UI, validation, API, authorization, database, audit, test, dan error state yang diperlukan untuk outcome tersebut.

Contoh implementation prompt:

Implement hanya target yang didefinisikan oleh prompt saat ini sesuai manifest/implementation guide.

Sebelum edit:
- ringkas scope;
- sebutkan target files;
- sebutkan acceptance criteria;
- sebutkan risiko.

Rules:
- jangan memperluas scope;
- jangan mengganti stack/schema/dependency tanpa alasan dan approval;
- ikuti DESIGN.md untuk UI;
- jangan gunakan secret production.

Setelah edit:
- jalankan checks yang tersedia;
- review git diff;
- laporkan files changed, tests, dan sisa risiko.

Jangan lanjut ke PROMPT_2 sampai stage ini direview.

Untuk Prompt 3, ganti kalimat terakhir menjadi: Jangan lanjut ke vertical slice berikutnya sampai slice ini direview dan di-commit.

Step 10 - Verification Setelah Setiap Stage

Engineering checks

Gunakan command yang tersedia:

npm run lint
npm run typecheck
npm test
npm run build

Git checks

git status
git diff

UI checks

Untuk screen yang berubah:

• desktop viewport;
• mobile viewport;
• loading;
• empty;
• error;
• validation;
• hover/focus;
• long content;
• accessibility keyboard basics.

Database/auth checks

• migration aman;
• tenant/user isolation;
• authorization server-side;
• secret tidak ke client;
• destructive change tidak tersembunyi;
• error path diuji.

Step 11 - Commit Satu Stage / Satu Meaningful Change

Contoh:

git add .
git commit -m "feat: implement onboarding foundation"

Commit kecil membuat:

• rollback mudah;
• diff mudah dibaca;
• usage limit reset tidak menghancurkan progress;
• agent baru dapat melanjutkan dari state stabil;
• conflict lebih mudah diselesaikan.

Step 12 - Kapan Menggunakan Git Worktree?

Setelah baseline stabil, Anda dapat memakai worktree untuk parallel task yang benar-benar terpisah.

Contoh:

git worktree add ../myapp-ui -b ai/ui
git worktree add ../myapp-api -b ai/api

Aturan:

• satu agent per worktree;
• jangan edit file shared yang sama tanpa ownership;
• merge satu branch pada satu waktu;
• re-run tests setelah merge.

Pemula tidak perlu worktree pada hari pertama.

Step 13 - Jika Usage Limit Habis di Tengah Pekerjaan

Jangan panik dan jangan mulai ulang project.

1. Pastikan perubahan saat ini sudah valid.
2. git status dan git diff.
3. Commit pekerjaan yang selesai.
4. Tulis HANDOFF.md atau update PLAN.md:
   • completed;
   • pending;
   • failing tests;
   • next files;
   • exact next step.
5. Tunggu reset atau pindah model/provider hanya bila policy/account Anda membolehkan.
6. Agent berikutnya harus membaca handoff sebelum edit.

Contoh:

# Handoff

## Done
- Project scaffold
- Auth UI shell

## Pending
- OAuth callback integration

## Current checks
- lint: pass
- typecheck: pass
- test: 28/28
- build: pass

## Next step
Implement PROMPT_2 only. Start by reading ...

Step 14 - Final Quality Gate

Sebelum menyebut project “selesai”:

• Semua acceptance criteria PRD yang in-scope terverifikasi.
• Tidak ada feature tambahan yang diam-diam masuk scope.
• Build/lint/typecheck/test relevan pass.
• Auth/authorization/data isolation direview.
• Migration direview.
• .env* dan secret aman.
• UI responsive.
• Empty/loading/error/validation states tersedia.
• Accessibility basics selesai.
• Asset placeholder teridentifikasi.
• DESIGN.md masih sesuai implementation.
• Final git diff direview.
• Preview deployment diuji sebelum production.

15. Ringkasan Workflow

EXTRACT ZIP
→ PROTECT SECRETS
→ GIT BASELINE
→ READ MANIFEST/GUIDE/PRD/SCHEMA
→ ANALYZE-ONLY PROMPT
→ PLAN.md
→ SCAFFOLD
→ 2-3 UI REFERENCES
→ DESIGN.md + ASSETS
→ PROMPT/STAGE 1
→ CHECK + DIFF + COMMIT
→ NEXT STAGE
→ FINAL QUALITY GATE
→ PREVIEW DEPLOY

16. Kesalahan yang Harus Dihindari

• paste seluruh ZIP ke chat tanpa struktur;
• menjalankan Prompt 1-5 sekaligus;
• memberi production secret;
• membiarkan agent mengganti stack tanpa approval;
• membuat 20 screen sebelum design direction disetujui;
• menganggap shadcn/ui otomatis berarti design bagus;
• memakai Magic UI di setiap component;
• menjalankan beberapa agents di folder yang sama;
• tidak memakai Git;
• tidak melihat diff;
• menganggap tests yang ditulis agent pasti benar;
• menganggap “build pass” berarti UX bagus;
• deploy production tanpa preview/review.