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.

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

Nama dan jumlah file dapat berbeda.

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 - First Prompt: Analyze Only

Jangan langsung berkata “buat aplikasi ini sampai selesai”.

Gunakan prompt:

Baca manifest, implementation guide, PRD, database schema, docs, dan AGENTS/AGENT jika ada.
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.

Jangan membuat asumsi produk baru jika dokumen tidak menjelaskannya.

Review plan sebagai manusia.

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

Contoh implementation prompt:

Implement hanya stage yang didefinisikan oleh PROMPT_1.md 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.

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.