# AI Agent Documentation Standards

Standar **Project Knowledge Preservation** untuk monorepo, dioptimalkan agar agent berikutnya lanjut kerja dengan **token minimal** (< 2000 token cold start).

---

## Struktur

```
AI-Agent-Standards/
├── README.md
├── recommendations.md
├── cursor-rule-project-handover.mdc
├── prompts/
│   ├── end-of-session-handover.md
│   └── generate-ai-session-summary.md
├── templates/
│   ├── handover-checklist.md
│   ├── repo/
│   │   ├── AGENTS.md              <- cold start (copy ke ROOT project)
│   │   ├── context-index.md       <- peta domain (on-demand, boleh tebal)
│   │   ├── ai-session-summary.md  <- rolling memory (max 80 baris)
│   │   ├── project-status.md
│   │   ├── todo.md
│   │   ├── changelog.md
│   │   ├── version.md
│   │   ├── server.md             <- host/IP, docker, nginx, DB
│   │   ├── issues.md
│   │   ├── adr-template.md
│   │   ├── api/README.md
│   │   └── guide/README.md
│   └── workspace/
└── examples/
```

---

## Cold start (paling penting)

```
Workspace-Session.md (Active focus)   # jika multi-project
  -> {project}/AGENTS.md              # ~200-400 token
  -> {project}/docs/ai-session-summary.md   # TL;DR + Lanjut + Jangan
  -> STOP - mulai kerja
```

On-demand saja: todo, issues, api, guide, server.md, context-index, adr.

**Jangan cold-start:** changelog penuh, version history, WORKLOG, development-log.

**Rolling session memory = hanya** `docs/ai-session-summary.md`.
File kronologis lain = arsip.

---

## Read budget

| Tujuan | Baca maksimal |
|--------|----------------|
| Lanjut task yang sama | AGENTS + ai-session-summary |
| Ambil task baru | + todo.md (High) |
| Debug | + issues.md (ID terkait) |
| Deploy / koneksi / infra | + docs/server.md |
| Ubah API | + docs/api/ |
| Flow / prosedur | + docs/guide/ |
| Arsitektur | + docs/adr/ |
| Navigasi domain | + context-index (Zona B) |

---

## Batas keras tulis

| File | Batas |
|------|-------|
| `AGENTS.md` | ~40 baris |
| `ai-session-summary.md` | **80 baris / ~1500 token**; wajib TL;DR + Lanjut + Jangan |
| `Workspace-Session.md` | ~50-100 baris; wajib Active focus |

---

## Struktur per subproject

```
{project}/
├── AGENTS.md                 # WAJIB - cold start (root project)
├── .env.example              # template URL/env (wajib)
└── docs/
    ├── ai-session-summary.md # rolling memory (OVERWRITE)
    ├── context-index.md      # peta (Zona A pointers + Zona B on-demand)
    ├── project-status.md
    ├── todo.md
    ├── changelog.md
    ├── version.md
    ├── server.md             # host/IP, runtime, DB (wajib)
    ├── system-requirements.md  # OS, runtime, tool (wajib)
    ├── issues.md
    ├── adr/
    ├── api/                  # jika API / framework API
    └── guide/                # wajib migration.md + guide lain
```

---

## Tier handover

| Tier | Kapan | File |
|------|-------|------|
| **1 Minimal** | Perubahan kode/config | session (TL;DR) + todo + changelog + version (+ AGENTS jika perlu) |
| **Deploy** | Install ke device/server, rilis APK/binary, cutover prod | **Wajib** append `version.md` (bullet poin) + bump versi build config |
| **2 Relevan** | Kondisi terpenuhi | issues, adr, guide, server.md, system-requirements, .env.example, migration, status, context-index, api |
| **3 Monorepo** | Multi-project | Workspace-Session (Active focus) |

---

## Single owner

| Informasi | Owner |
|-----------|-------|
| Cold start / aturan kritis | `AGENTS.md` |
| Narasi sesi (rolling) | `ai-session-summary.md` |
| Priority | `todo.md` |
| Bug / RCA | `issues.md` |
| Changelog | `changelog.md` |
| Poin versi | `version.md` — **wajib append setiap deploy/naik versi** |
| API | `docs/api/` |
| Flow prosedur | `docs/guide/` |
| Server / IP / runtime / DB | `docs/server.md` |
| System requirements | `docs/system-requirements.md` |
| URL/env template | `.env.example` |
| Migrasi server/domain | `docs/guide/migration.md` |
| Peta domain | `context-index.md` |
| Lintas project | `Workspace-Session.md` |

Pengetahuan penting, arsitektur, flow, inventori server, system requirements, migrasi **tidak boleh** hanya di chat. **No hardcoded URL.**

---

## Setup subproject baru

1. Copy `templates/repo/AGENTS.md` ke **root** project (sibling `docs/`)
2. Copy sisa `templates/repo/*` ke `{project}/docs/`
3. Isi AGENTS.md (pendek) dan context-index Zona A
4. Daftarkan di `Workspace-Context.md`

## Quick command

```
Lakukan Project Knowledge Preservation sesuai standar di
AI-Agent-Standards/prompts/end-of-session-handover.md
```

## Cursor

Salin `cursor-rule-project-handover.mdc` ke `.cursor/rules/`

---

## No hardcoded URL

- Semua URL/domain/host dari `.env` / env var / BuildConfig
- Template commit: `.env.example`; secret hanya di `.env` lokal (gitignore)
- Migrasi: update .env.example, server.md, guide/migration.md`r

## Bootstrap project baru (salin ke agent)

Prompt siap pakai: [prompts/bootstrap-new-project.md](prompts/bootstrap-new-project.md)

Agent akan membaca template lalu membuat AGENTS.md + docs/ untuk satu atau lebih subproject, dan mendaftarkannya di Workspace-Context.md.

Contoh:

```
Ikuti AI-Agent-Standards/prompts/bootstrap-new-project.md

projects:
  - path: lagercloud.com/billing
    name: Billing
    description: Service tagihan
    stack: Python FastAPI
    type: api
    has_api: true
```