Markdown, Repository Rules, dan Git Worktree

AI coding menjadi jauh lebih stabil ketika repository mempunyai instruksi yang jelas dan setiap agent bekerja pada scope yang terisolasi.

1. Mengapa Markdown Cocok untuk Instruksi Agent

Markdown adalah plain text yang bisa dibaca manusia, Git, search tool, dan model AI. Ia sangat cocok untuk menyimpan knowledge yang harus tetap dekat dengan code.

Kelebihan untuk AI coding:

• heading membuat hierarchy jelas;
• table cocok untuk rule/decision matrix;
• code block mempertahankan command/example;
• diff Git mudah dibaca;
• tidak bergantung pada editor tertentu;
• dapat direview melalui pull request;
• mudah dirujuk agent dengan path tertentu.

Markdown bukan “format ajaib yang selalu otomatis dimasukkan ke context”. Coding tool tetap menentukan file mana yang auto-discover/read.

Untuk membaca hasil render tanpa memasang extension, buka FileMira Markdown Viewer. Viewer ini menampilkan source dan hasil render berdampingan serta memproses file secara lokal di browser menurut halaman produknya. Jangan masukkan file yang masih berisi secret.

2. Struktur Markdown yang Direkomendasikan

README.md          → cara menjalankan project
AGENTS.md          → repository rules lintas agent yang mendukungnya
CLAUDE.md          → Claude Code project instructions
GEMINI.md          → Gemini CLI project context
PRD.md             → requirement produk
DESIGN.md          → visual/UX contract
PLAN.md            → task plan aktif
ASSETS.md          → asset inventory

Tidak semua project perlu semua file. Gunakan sedikit file tetapi jelas ownership-nya.

3. Apa Itu JSON, CSV, YAML, dan TOML?

Project modern tidak hanya berisi Markdown. Empat format berikut sering muncul sebagai konfigurasi, manifest, atau data:

Aturan aman:

• jangan mengubah format hanya karena file sulit dibaca;
• pertahankan indentation, quote, comma, dan tipe data;
• validasi setelah edit;
• jangan menaruh comment di JSON bila parser tidak mendukungnya;
• lihat diff sebelum commit;
• hapus secret, token, credential, dan personal data sebelum memakai viewer apa pun.

4. Apa yang Layak Masuk Repository Instructions?

Masukkan hal yang stabil dan reusable:

• stack dan version constraints;
• command install/test/build;
• directory ownership;
• style/convention penting;
• security rules;
• migration policy;
• dependency policy;
• definition of done;
• file/area yang tidak boleh diubah sembarangan.

Hindari:

• secret/API key;
• requirement sementara satu ticket;
• chat transcript panjang;
• semua dokumentasi vendor yang bisa di-link;
• aturan kontradiktif;
• tutorial yang sudah deprecated.

Contoh AGENTS.md portable:

# Repository Instructions

## Source of truth
- Product: `docs/PRD.md`
- Design: `DESIGN.md`
- Database: `docs/schema.md`

## Commands
- Install: `npm ci`
- Dev: `npm run dev`
- Lint: `npm run lint`
- Typecheck: `npm run typecheck`
- Test: `npm test`
- Build: `npm run build`

## Engineering rules
- Preserve existing architecture unless the task explicitly changes it.
- Do not add dependencies without explaining why existing code is insufficient.
- Never commit `.env.local` or secrets.
- Database changes require migration + rollback/verification note.

## Definition of done
- Acceptance criteria satisfied.
- Lint/typecheck/test/build relevant to change pass.
- `git diff` reviewed.
- No unrelated files changed.

5. Apa Itu Branch dan Worktree?

Branch adalah pointer/line of development di Git.

Worktree adalah folder checkout terpisah yang terhubung ke repository Git yang sama. Dengan worktree, Anda dapat memiliki beberapa branch aktif di beberapa folder sekaligus tanpa clone penuh yang terpisah.

Mental model:

repository Git yang sama
├── folder utama       → branch main
├── ../project-ui      → branch ai/ui
└── ../project-api     → branch ai/api

Dokumentasi Git menjelaskan worktree sebagai cara mengelola beberapa working trees yang terhubung pada repository yang sama. Secara normal, branch yang sama tidak checkout di dua worktree sekaligus.

Sumber: https://git-scm.com/docs/git-worktree

6. Kapan Worktree Berguna untuk AI Coding?

Gunakan worktree bila:

• dua agent perlu mengerjakan task berbeda secara paralel;
• satu task eksperimental tidak boleh mengganggu folder utama;
• Anda ingin membandingkan dua implementasi pada branch berbeda;
• bugfix urgent berjalan saat feature besar masih aktif.

Jangan gunakan worktree hanya karena terlihat advanced. Untuk pemula, satu agent + satu branch + commit kecil lebih mudah dipahami.

7. Tutorial Git Worktree

Pastikan branch utama bersih:

git status

Buat worktree UI dengan branch baru:

git worktree add ../project-ui -b ai/ui

Buat worktree API:

git worktree add ../project-api -b ai/api

Lihat daftar:

git worktree list

Sekarang buka terminal/agent terpisah:

project-ui  → agent A → hanya task UI
project-api → agent B → hanya task API

Setelah branch selesai dan sudah di-merge, hapus worktree yang tidak dipakai:

git worktree remove ../project-ui

Jangan menghapus folder worktree secara manual sebelum memahami status Git-nya.

8. Aturan Parallel AI Agents

Jika menggunakan lebih dari satu agent:

1. Satu agent per worktree.
2. Satu branch per worktree.
3. Pisahkan ownership file sedapat mungkin.
4. Jangan biarkan dua agent mengubah migration/schema yang sama bersamaan.
5. Jangan biarkan dua agent menambah dependency/config global tanpa koordinasi.
6. Setiap agent harus menjalankan verification untuk scope-nya.
7. Merge satu per satu ke integration branch/main.
8. Setelah merge pertama, rebase/update branch kedua sebelum final merge bila perlu.
9. Human review conflict resolution.
10. Jangan memakai worktree sebagai alasan untuk menjalankan banyak agent tanpa plan.

9. Worktree vs Clone vs Branch Biasa

Untuk AI coding local parallelism, worktree sering lebih ringan daripada clone kedua.

10. File Ownership untuk Mengurangi Conflict

Contoh:

# Parallel Work Plan

## ai/ui
Owns:
- app/(marketing)/**
- components/marketing/**
- public/marketing/**

Must not edit:
- database/migrations/**
- server/auth/**

## ai/api
Owns:
- server/api/**
- lib/data/**

Must not edit:
- app/(marketing)/**

Jika satu file shared harus berubah, tentukan satu owner dan biarkan agent lain menunggu/consume hasil merge.

11. Recovery Commands yang Perlu Dipahami

Sebelum memakai autonomous agent, pahami minimal:

git status
git diff
git log --oneline --decorate -n 10
git restore <file>
git switch <branch>
git worktree list

Jangan menggunakan reset/rebase/destructive commands hanya karena agent menyarankan. Pahami efeknya terlebih dahulu.

12. Checklist Repository AI-Ready

• Git baseline bersih.
• Repository instructions tersedia.
• README memiliki command yang benar.
• Secret di-ignore.
• PRD/requirements dapat ditemukan.
• DESIGN.md tersedia bila UI perlu brand direction.
• Agent tahu test/build command.
• Satu agent per working tree.
• Worktree hanya digunakan bila parallelism benar-benar membantu.
• Merge conflict diselesaikan manusia atau agent dengan human verification.