AGENTS.md ยท diff

git:20260107.0787a0b to git:20260108.29106b1

1 added, 1 removed. Audit A to A.

What this update changes in the checks

No check changed: every fixed check gives the same answer before and after this update.

A tripped check is a label, not a verdict: read the matched text and the lines below. This week's updates that newly trip a check.

# AGENTS.md
> AI Agent Instructions for this project. Didukung oleh GitHub Copilot, Cursor, Kiro, Antigravity, dll.
*Stats: 237 entries (59 gotchas, 110 patterns, 25 decisions, 41 context)*
---
## ๐Ÿ“‹ Project Overview
**Project:** andy-universal-agent-rules
**Purpose:** Testing & documentation AI agent rules system
**Stack:** Multi-platform (PHP, Node.js, Python) - See `.agent/context/environment.json` for detected versions.
---
## ๐Ÿ› ๏ธ Tech Stack & Environment
> **NOTE:** Actual versions are auto-detected in `.agent/context/environment.json`.
- **Backend:** PHP 8.4+, Node.js 20.x+
- **Database:** MySQL (3306), Oracle 11g (1521)
- **Tools:** Laragon (Win), Valet/Homebrew (Mac), Native (Linux)
- **OS:** Cross-Platform (Windows/Linux/macOS)
---
## ๐Ÿ˜ Multi-PHP Version Support
> **Available PHP Versions (Linux):** 5.6, 7.2, 8.3, 8.4, 8.5
### Per-Project PHP Version
```bash
# Check default PHP
php -v
# Use specific version
php5.6 script.php
php7.2 artisan serve
php8.4 composer install
# Check all available
ls /usr/bin/php*
```
### Project-Specific Configuration
Untuk project yang membutuhkan PHP tertentu, gunakan:
| Method | File/Command | Example |
|--------|--------------|---------|
| **Shebang** | Script header | `#!/usr/bin/php7.2` |
| **Composer** | `composer.json` | `"php": "^7.2"` |
| **Apache** | `.htaccess` | `SetHandler application/x-httpd-php72` |
### Gotchas per Version
| PHP Version | Known Issues |
|-------------|--------------|
| **5.6** | No arrow functions, MySQL charset issues |
| **7.2** | No typed properties, limited union types |
| **8.3+** | Full modern PHP features |
> ๐Ÿ“š **Related:** `.agent/memory/entries/gotchas/php72-arrow-function.md`
---
## โšก Quick Commands
```bash
# PHP Project
composer install
php artisan serve
# Node.js Project
npm install
npm run dev
# Knowledge Management
python .agent/.agent/scripts/save-knowledge.py --category gotchas "message"
python .agent/.agent/scripts/search-knowledge.py "oracle commit"
python .agent/.agent/scripts/validate-index.py --fix
# Backup (auto-timestamp & compression)
python .agent/.agent/scripts/backup-memory.py # Quick backup
python .agent/.agent/scripts/backup-memory.py --list # List backups
python .agent/.agent/scripts/backup-memory.py --restore <file>
# Environment
python .agent/.agent/scripts/detect-environment.py
# Python Testing & Validation
python .agent/context/python_capability_test.py
python .agent/context/test_new_packages.py
```
---
## ๐Ÿ Python Capabilities
Agent memiliki Python 3.13.5 dengan **11 third-party packages** untuk berbagai keperluan:
### Web & Data
| Package | Kegunaan | Example Use Case |
|--------------------|---------------|----------------------------------------|
| **requests** | HTTP requests | API calls, download files |
| **beautifulsoup4** | HTML parsing | Web scraping, extract data dari HTML |
| **lxml** | XML parsing | Parse XML configs, RSS feeds |
### Data Processing
| Package | Kegunaan | Example Use Case |
|------------|---------------------|---------------------------------------|
| **pandas** | Data analysis | Olah CSV/Excel, statistical analysis |
| **numpy** | Numerical computing | Matrix operations, calculations |
### Config & Formats
| Package | Kegunaan | Example Use Case |
|------------|-------------|----------------------------------------|
| **pyyaml** | YAML parser | Parse docker-compose.yml, k8s configs |
| **toml** | TOML parser | Parse pyproject.toml, modern configs |
### Development Tools
| Package | Kegunaan | Example Use Case |
|------------|-------------------|------------------------------------|
| **pytest** | Testing framework | Unit tests, integration tests |
| **pylint** | Code linter | Check code quality, find bugs |
| **black** | Code formatter | Auto-format Python code |
| **pillow** | Image processing | Resize, convert, manipulate images |
### ๐Ÿ’ก Use Cases untuk AI Agent
```python
# Web Scraping
from bs4 import BeautifulSoup
soup = BeautifulSoup(html, 'html.parser')
data = soup.find_all('div', class_='product')
# Data Analysis
import pandas as pd
df = pd.read_csv('data.csv')
summary = df.describe()
# Config Parsing
import toml
config = toml.load('config.toml')
# Image Processing
from PIL import Image
img = Image.open('photo.jpg')
img.thumbnail((800, 600))
```
> ๐Ÿ“š **Test Results:** `.agent/context/benchmark-results.txt`
---
## ๐ŸŽฏ Multi-Tech Quick Reference
> Agent dapat bekerja dengan berbagai jenis project. Gunakan referensi ini untuk menentukan tools yang tepat.
| Project Type | Primary Tech | Tools/Framework | Memory Reference |
|--------------|--------------|-----------------|------------------|
| **Web App (PHP)** | PHP 5.6-8.5 | Laravel, Yii, Native | See Multi-PHP section |
| **Web App (Node)** | Node.js 24.x | Express, Next.js, Vite | `npm run dev` |
| **Mobile (Android)** | Flutter/Dart | Android Studio, Firebase | `flutter-development-guide.md` |
| **Desktop** | Electron/Flutter | Cross-platform | Flutter Desktop |
| **Reports/Data** | Python | pandas, numpy, matplotlib | `python-automation-capabilities.md` |
| **API/Backend** | PHP/Node | REST, GraphQL | Native frameworks |
### Quick Start per Project Type
```bash
# Web PHP
php artisan serve # Laravel
php -S localhost:8000 # Native
# Web Node
npm run dev # Vite/Next.js
# Mobile Android
flutter run -d android # Flutter
flutter build apk --release # Build APK
# Data/Reports
python3 scripts/generate-report.py
```
---
## ๐Ÿ“‚ Strict File Organization Rules
> **๐Ÿšจ CRITICAL:** Agent **DILARANG KERAS** membuat file baru sembarangan di ROOT directory project (`/`).
> Lihat struktur lengkap di: `PROJECT_STRUCTURE.md`.
### ๐Ÿšซ Forbidden Actions
1. **NO Root Clutter:** Jangan pernah buat file testing, script one-off, atau log di root.
2. **NO Temp Files:** Jangan tinggalkan file `test.py`, `output.txt`, atau `temp.json` di root.
### โœ… Mandatory Locations
File baru harus ditempatkan sesuai kategorinya:
| Tipe File | Lokasi Wajib | Keterangan |
| :--- | :--- | :--- |
| **Python Tests** | `test/python/` | Unit testing, pytest script |
| **PHP Database Tests** | `test/database/<db_name>/` | MySQL/Oracle connection tests |
| **Utility Scripts** | `scripts/` | Automation tools |
| **Temporary Files** | `test/temp/` | File debug/sementara (tidak di-commit) |
| **Dokumentasi** | `test/<category>/README.md` | Doc untuk script spesifik |
**Contoh Pelanggaran:**
- โŒ Membuat `calculator.py` di root โ†’ Pindah ke `test/python/`
- โŒ Membuat `debug_log.txt` di root โ†’ Pindah ke `test/temp/`
---
## ๐Ÿ“ Coding Conventions
### General
- Use **UTF-8** encoding for all files
- Use **4 spaces** for indentation (no tabs)
- Max line length: **120 characters**
### PHP
- Follow **PSR-12** coding standard
- Use **type hints** for all function parameters and return types
- All classes must have **docblocks**
### JavaScript/Node.js
- Use **ESLint** with recommended rules
- Prefer **const** over let, avoid var
- Use **async/await** over callbacks
### Python
- Follow **PEP 8** style guide
- Use **type hints** (Python 3.10+)
- Use **f-strings** for formatting
### Markdown Tables
- **Align columns** dengan padding spaces agar rata
- **Bold** item penting di kolom pertama (e.g., `**PHP**`)
- **Tambah emoji status** jika ada state (โœ… โŒ โš ๏ธ)
- Separator `|---|` harus sama panjang dengan header
```markdown
# โŒ SALAH - Tidak rata, tidak bold
| Platform | Status |
|---|---|
| PHP | Done |
# โœ… BENAR - Rata, bold, emoji
| Platform | Status | Notes |
|------------|--------|------------------|
| **PHP** | โœ… | Production ready |
| **Python** | โš ๏ธ | Needs testing |
```
### โš ๏ธ Python Execution
**Linux/macOS (Bash):**
```bash
# โœ… Single line
python3 -c "import os; print('hello')"
# โœ… Multiline (Heredoc)
python3 <<EOF
import os
print('hello')
EOF
```
**Windows (PowerShell):**
```powershell
# โŒ JANGAN - Multiline python -c akan STUCK!
python -c "
import os
print('hello')
"
```
# โœ… BENAR - Buat file .py terlebih dahulu
python .agent/context/temp_script.py
# โœ… ATAU - Single line dengan semicolon
python -c "import os; print('hello')"
```
> ๐Ÿ“š **Detail:** `.agent/memory/entries/gotchas/python-powershell-multiline-commands.md`
---
## โš ๏ธ Critical Gotchas
> **Full database:** lihat `.agent/memory/entries/gotchas/`
### Database
#### Oracle Transaction Commit Bug ๐Ÿšจ
```php
// โŒ SALAH - Data hilang setelah 15 menit!
$model->save();
// โœ… BENAR - Explicit COMMIT
$transaction->commit();
Yii::app()->db->getPdoInstance()->exec("COMMIT");
```
#### MySQL Windows Connection
```php
// โŒ SALAH - Bisa gagal di Windows
'host' => 'localhost'
// โœ… BENAR
'host' => '127.0.0.1'
```
### Git
- โŒ JANGAN `git reset --hard` tanpa backup
- โŒ JANGAN force push ke `main` atau `develop`
- โœ… SELALU buat branch untuk fitur baru
- โœ… **SELALU buat GitHub repo sebagai PRIVATE** (user preference)
### GitHub Repository Creation
```bash
# โœ… BENAR - Private by default
gh repo create NAMA_REPO --private --source=. --remote=origin --push
# โŒ SALAH - Public (hanya jika diminta eksplisit)
gh repo create NAMA_REPO --public --source=. --remote=origin --push
```
---
## ๐Ÿงญ Best Practices: Tool Selection Strategy
Untuk kinerja optimal, gunakan decision tree berikut saat memilih tool.
### 1. Web Browsing Hierarchy
*Goal: Hemat waktu & resource.*
1. **Butuh info dari dokumentasi/artikel statis?** โ†’ Gunakan `read_url_content` (Cepat, Text-only).
2. **Butuh solusi error umum?** โ†’ Gunakan `search_web`.
3. **Butuh login, UI visual, atau SPA dynamic?** โ†’ Gunakan `browser_subagent`.
4. **Butuh mass automation/testing?** โ†’ Gunakan `Playwright MCP`.
> ๐Ÿ“š **Detail:** `.agent/memory/entries/patterns/browsing-tool-hierarchy.md`
### 2. Scripting Language: Python vs Node.js
*Goal: Efisiensi coding & performance.*
- | Kebutuhan | Pilih Bahasa | Alasan |
+ | Requirement | Choose Language | Reason |
| :--- | :--- | :--- |
| **Data Processing (CSV/Excel)** | **Python** ๐Ÿ | Pandas jauh lebih cepat & mudah |
| **Simple Automation** | **Python** ๐Ÿ | Standard library (OS, Sys) robust |
| **API Batch Operations** | **Node.js** ๐Ÿ“ฆ | Native Async/Await non-blocking |
| **Project Integration** | **Node.js** ๐Ÿ“ฆ | Reuse existing project logic |
> ๐Ÿ“š **Detail:** `.agent/memory/entries/decisions/python-vs-nodejs-scripting.md`
### 3. External AI Tools: Gemini CLI vs Jules
*Goal: Pilih tool AI paling tepat untuk setiap task.*
> **๐Ÿšจ IMPORTANT HIERARCHY:**
> 1. **PRIMARY:** Built-in AI dari Code Editor (Gemini 3 / Claude Anthropic) โ†’ **GUNAKAN INI DULU!**
> 2. **SUPPORT:** Gemini CLI, Jules CLI, MCP โ†’ Gunakan sebagai **ASYNC/PARALLEL** support saja
>
> External tools JANGAN mengganggu responsivitas primary AI. Gunakan hanya untuk task spesifik yang memerlukan!
#### Kapan Gunakan External Tools (Async/Parallel)?
| Kondisi | Tool Support | Mode | Alasan |
| :--- | :--- | :--- | :--- |
| **Task berat yang butuh waktu lama** | `jules new` | ๐Ÿ”„ Async | Jalan di background, tidak block editor |
| **Quota primary AI habis** | `gemini -p` | ๐Ÿ”„ Async | Backup saat limit tercapai |
| **Butuh akses ke service eksternal** | MCP Servers | ๐Ÿ”„ Parallel | GitHub, Firebase, database |
| **Generate file batch** | `jules new` | ๐Ÿ”„ Async | Multi-file tanpa ganggu workflow |
| **Debug error kompleks** | `gemini -p` | ๐Ÿ”„ Quick | Second opinion cepat |
#### โŒ JANGAN Gunakan External Tools Untuk:
- Task yang bisa dikerjakan langsung oleh built-in AI
- Operasi simple yang mengganggu flow kerja
- Menggantikan primary AI untuk task standar
#### Use Cases untuk External Tools (Async Only):
| Task Type | Tool Support | Mode | Kapan Digunakan |
| :--- | :--- | :--- | :--- |
| **Multi-file Generation** | `jules new` | ๐Ÿ”„ Async | Banyak file sekaligus |
| **Refactoring Massal** | `jules new` | ๐Ÿ”„ Async | Complex changes |
| **Documentation Full** | `jules new` | ๐Ÿ”„ Async | Multiple docs |
| **Code Migration** | `jules new` | ๐Ÿ”„ Async | Language conversion |
| **Second Opinion** | `gemini -p` | ๐Ÿ”„ Quick | Debug/verify |
| **Quota Backup** | `gemini -p` | ๐Ÿ”„ Quick | Primary AI limit |
**Decision Tree (UPDATED):**
```
Butuh bantuan AI?
โ”‚
โ”œโ”€ Bisa dikerjakan built-in AI (Gemini 3 / Claude)?
โ”‚ โ””โ”€ โœ… GUNAKAN BUILT-IN AI (PRIMARY) โ† DEFAULT!
โ”‚
โ”œโ”€ Task berat / multi-file / butuh waktu lama?
โ”‚ โ””โ”€ โœ… Gunakan: jules new "..." (ASYNC, jalan di background)
โ”‚
โ”œโ”€ Quota primary AI habis?
โ”‚ โ””โ”€ โœ… Fallback: gemini -p "..." (External CLI)
โ”‚
โ””โ”€ Butuh akses service eksternal (GitHub, DB, etc)?
โ””โ”€ โœ… Gunakan: MCP Servers (PARALLEL)
```
**Quick Commands (Support Tools Only):**
```bash
# Jules (background async - tidak block editor)
jules new "Buat unit test untuk semua file di src/"
jules remote list --session
jules remote pull --session ID --apply
# Gemini CLI (fallback/second opinion)
gemini -p "Fix error: [paste error]"
```
> ๐Ÿ“š **Detail:** `.agent/memory/entries/patterns/gemini-cli-*.md`, `jules-cli-*.md`
### 4. Complete Tool Priority Matrix
*Goal: Built-in AI FIRST, external tools sebagai SUPPORT.*
| Task | 1st Choice (PRIMARY) | 2nd Choice (SUPPORT) | 3rd Choice |
| :--- | :--- | :--- | :--- |
| **Code Generation** | **Built-in AI** | Jules (async) | - |
| **Code Review** | **Built-in AI** | Gemini CLI | - |
| **Error Debugging** | **Built-in AI** | Gemini CLI | - |
| **Refactoring** | **Built-in AI** | Jules (async) | - |
| **Documentation** | **Built-in AI** | Jules (async) | - |
| **GitHub PR/Issues** | MCP GitHub | `gh` CLI | - |
| **Database Query** | PHP PDO/OCI8 | MCP DBeaver | CLI |
| **Redis Cache** | `redis-cli` | MCP Redis | - |
| **Browser Testing** | MCP Playwright | browser_subagent | - |
> **INGAT:** External tools (Gemini CLI, Jules, MCP) = **ASYNC/PARALLEL SUPPORT ONLY!**
> Jangan block workflow primary AI dari code editor.
---
## ๐Ÿ” Safety Rules
### Konfirmasi Wajib Sebelum:
1. **Delete operations:** `rm`, `del`, `DROP TABLE`, `TRUNCATE`
2. **Git destructive:** `reset --hard`, `clean -fd`, force push
3. **Package install:** `npm install`, `composer require`
4. **External requests:** API calls ke production
### File Sensitif (NO ACCESS):
```
.env, .env.*, *.env
*.pem, *.key, id_rsa
config/database.php
credentials/*, secrets/*
```
---
## ๐Ÿ”Œ MCP Servers (Available Tools)
Agent memiliki akses ke 6 MCP servers. Gunakan sesuai kebutuhan:
| MCP Server | Fungsi | Kapan Digunakan |
|-------------------------|---------------------------|------------------------------|
| **GitHub** | Repo, PR, Issues | Git operations yang kompleks |
| **Firebase** | Auth, Firestore, Hosting | Firebase projects |
| **Cloud Run** | GCP deployment | Deploy ke Google Cloud |
| **Dart** | Flutter/Dart projects | Mobile app development |
| **Redis** | Cache, key-value store | Data caching & sessions |
| **Sequential Thinking** | Problem solving | Complex reasoning tasks |
### Local Custom MCP Servers
> **STATUS:** โœ… All 8 servers PASSED validation (Verified 2026-01-02 via `validate-servers.js`)
Server-server ini dijalankan via `start-mcp.ps1` atau config editor:
| MCP Server | Type | Function | Status (Test 2026-01-02) |
|---------------------|---------|-----------------|---------------------------|
| **DBeaver** | Python | Multi-DB Access | โœ… Ready (Found venv) |
| **Oracle** | Node.js | Oracle DB | โœ… Ready |
| **Postgres** | Node.js | Postgres DB | โœ… Ready |
| **Chrome DevTools** | Node.js | Browser Debug | โœ… Ready |
| **Playwright** | Node.js | Automation | โœ… Ready |
| **Context7** | Node.js | Context Mgmt | โœ… Ready |
| **Blogger** | Node.js | Blog Management | โœ… Ready |
| **LangChain** | Node.js | AI Workflows | โœ… Ready |
### Quick Reference (Built-in)
> **โš ๏ธ WARNING:** redis-mcp-server failed testing ("Client closed"). Use `redis-cli` instead.
```bash
# GitHub - Get user info
mcp_github-mcp-server_get_me()
# Redis - Cache operations
# โŒ MCP Fails ("Client closed")
# mcp_redis_set({key: "key", value: "value"}) (DO NOT USE)
# โœ… Workaround: Use redis-cli
# 1. Setup Alias (PowerShell):
# Set-Alias redis-cli "path/to/redis-cli.exe"
# 2. Run commands:
redis-cli SET mykey "Hello"
redis-cli GET mykey
# Firebase - Get environment
mcp_firebase-mcp-server_firebase_get_environment()
```
### MCP vs Direct Access
| Task | Gunakan MCP | Gunakan Direct |
|-----------------|--------------------------|-----------------------------|
| Git operations | โœ… Complex (PR, Issues) | โœ… Simple (commit, push) |
| Redis cache | โœ… MCP Redis | โŒ PHP Redis (slower) |
| Database query | โŒ | โœ… PHP PDO/OCI8 (faster) |
| Firebase admin | โœ… MCP Firebase | - |
> ๐Ÿ“š **Detail:** `.agent/memory/entries/context/mcp-server-status-configuration.md`
---
## ๐Ÿค– Model-Specific Guidelines
> **CRITICAL:** MCP server compatibility berbeda antar AI model di Antigravity editor
### Claude Sonnet (Claude 3.5/4)
**MCP Compatibility:**
| MCP Server | Status | Reason |
|-------------------------|--------------|------------------------|
| **Redis** | โœ… **WORKS** | Local, no external API |
| **Sequential Thinking** | โœ… **WORKS** | Internal processing |
| **GitHub** | โŒ **HANGS** | External API timeout |
| **Firebase** | โŒ **HANGS** | External API timeout |
| **Cloud Run** | โŒ **HANGS** | External API timeout |
| **Dart** | โŒ **HANGS** | External API timeout |
**Recommended Usage:**
```markdown
โœ… SAFE untuk Claude Sonnet:
- Local file operations (view_file, write_to_file)
- Terminal commands (run_command)
- Redis MCP (caching, sessions)
- Sequential Thinking MCP (reasoning)
โŒ AVOID dengan Claude Sonnet:
- GitHub MCP โ†’ Use: git CLI, gh CLI
- Firebase MCP โ†’ Use: firebase CLI
- Cloud Run MCP โ†’ Use: gcloud CLI
- Dart MCP โ†’ Use: flutter CLI
```
### Gemini 3 (Gemini 2.0 Flash/Pro)
**MCP Compatibility:**
| MCP Server | Status |
|-----------------------|--------------|
| **ALL 6 MCP Servers** | โœ… **WORKS** |
**Recommended Usage:**
```markdown
โœ… SAFE untuk Gemini 3:
- Semua MCP servers available
- External API-based MCP (GitHub, Firebase, Cloud Run, Dart)
- Complex MCP workflows
- Multiple parallel MCP calls
```
### Model Selection Strategy
| Task Type | Recommended Model | Reason |
|-------------------------|-------------------|-----------------------------------|
| **GitHub operations** | โœ… Gemini 3 | GitHub MCP required |
| **Firebase deployment** | โœ… Gemini 3 | Firebase MCP required |
| **Cloud Run deploy** | โœ… Gemini 3 | Cloud Run MCP required |
| **Flutter development** | โœ… Gemini 3 | Dart MCP required |
| **Code analysis** | โœ… Claude Sonnet | Superior reasoning, no MCP needed |
| **Local development** | โœ… Claude Sonnet | File ops + Redis MCP sufficient |
| **Caching operations** | โœ… Both | Redis MCP works on both |
### Hybrid Workflow Pattern
Untuk workflow yang memerlukan both MCP dan code analysis:
```markdown
Step 1: Use Gemini 3
โ”œโ”€ Fetch data via GitHub MCP
โ”œโ”€ Deploy via Cloud Run MCP
โ””โ”€ Setup via Firebase MCP
Step 2: Switch to Claude Sonnet
โ”œโ”€ Analyze fetched data
โ”œโ”€ Code review & refactoring
โ””โ”€ Generate solutions
Step 3: Back to Gemini 3
โ””โ”€ Execute deployment via MCP
```
### CLI Alternatives (For Claude Sonnet)
Jika menggunakan Claude Sonnet, gunakan CLI tools sebagai pengganti MCP:
```bash
# Instead of GitHub MCP
git log -n 10
gh pr list
gh issue list
# Instead of Firebase MCP
firebase projects:list
firebase deploy
# Instead of Cloud Run MCP
gcloud run services list
gcloud run deploy
# Instead of Dart MCP
flutter devices
flutter run
flutter test
```
> ๐Ÿ“š **Testing Results:** Verified 2025-12-29 via systematic MCP testing
---
## ๐Ÿณ Docker MCP Infrastructure
> **INFO:** Beberapa MCP servers berjalan di Docker containers
### Docker MCP Toolkit (Beta)
> **STATUS:** โœ… Active (Verified 2026-01-02 via `docker mcp server list`)
Docker Desktop kini memiliki **MCP Toolkit** built-in yang berfungsi sebagai gateway untuk berbagai MCP servers.
**Command Gateway:**
```bash
docker mcp gateway run
```
Command ini menghubungkan MCP Client (Editor) dengan server-server yang dimanage oleh Docker.
**Installed Servers (Docker):**
* **Playwright** (Enabled) - Browser automation
* **GitHub** (Active Container: `ghcr.io/github/github-mcp-server`)
### GitHub MCP Server (Docker Container)
**Architecture:**
```
Docker Environment:
โ”œโ”€ Image: ghcr.io/github/github-mcp-server
โ”œโ”€ Instances: 2 containers (redundancy/load-balancing)
โ”‚ โ”œโ”€ Container 1: Primary instance
โ”‚ โ””โ”€ Container 2: Fallback instance
โ”œโ”€ Network: Internal Docker network
โ”œโ”€ Communication: MCP protocol (stdio/HTTP)
โ””โ”€ Version: 0.26.3 (as of 2025-12-29)
```
**Management Commands:**
```bash
# Check running MCP containers
docker ps | grep mcp
# Check all MCP containers (including stopped)
docker ps -a | grep mcp
# View container logs
docker logs <container_id> --tail 50
# Restart container if stuck
docker restart <container_id>
# Check container resource usage
docker stats <container_id>
```
**Troubleshooting:**
| Problem | Solution |
|---------|----------|
| MCP hangs | Check `docker ps -a`, restart if needed |
| No response | Check logs: `docker logs <id>` |
| Auth error | Verify GitHub token still valid |
| Container exited | `docker start <container_id>` |
---
## ๐Ÿ–ฅ๏ธ Editor-Specific MCP Support
> **CRITICAL:** MCP availability berbeda antar code editors
### Complete MCP Compatibility Matrix
| MCP Server | Antigravity (Gemini) | Antigravity (Claude) | VSCode (Copilot) | Cursor | Kiro | **Windsurf** |
|-------------------------|----------------------|----------------------|------------------|----------|-------------------------|--------------|
| **Redis** | โœ… Works | โœ… Works | โŒ N/A | โš ๏ธ Check | โŒ Not configured | โŒ CLI only |
| **Sequential Thinking** | โœ… Works | โœ… Works | โŒ N/A | โš ๏ธ Check | โœ… Works (auto-approve) | โœ… 3 tools |
| **GitHub** | โœ… Works | โŒ Hangs | โœ… PR Tools | โš ๏ธ Check | โœ… Works (git MCP) | โŒ CLI only |
| **Firebase** | โœ… Works | โŒ Hangs | โŒ N/A | โš ๏ธ Check | โŒ Not configured | โŒ CLI only |
| **Cloud Run** | โœ… Works | โŒ Hangs | โŒ N/A | โš ๏ธ Check | โŒ Not configured | โŒ CLI only |
| **Dart** | โœ… Works | โŒ Hangs | โŒ N/A | โš ๏ธ Check | โŒ Not configured | โŒ CLI only |
| **MySQL** | โŒ N/A | โŒ N/A | โŒ N/A | โš ๏ธ Check | โœ… Works (auto-approve) | โŒ CLI only |
| **SQLite** | โŒ N/A | โŒ N/A | โŒ N/A | โš ๏ธ Check | โœ… Works (auto-approve) | โŒ CLI only |
| **Filesystem** | โŒ N/A | โŒ N/A | โŒ N/A | โš ๏ธ Check | โœ… Works (auto-approve) | โŒ CLI only |
| **Chrome DevTools** | โŒ N/A | โŒ N/A | โŒ N/A | โš ๏ธ Check | โœ… Works (manual) | โŒ CLI only |
| **Puppeteer** | โŒ N/A | โŒ N/A | โŒ N/A | โš ๏ธ Check | โœ… Works (manual) | โŒ CLI only |
| **Lighthouse** | โŒ N/A | โŒ N/A | โŒ N/A | โš ๏ธ Check | โœ… Works (auto-approve) | โŒ CLI only |
| **Memory** | โŒ N/A | โŒ N/A | โŒ N/A | โš ๏ธ Check | โœ… Works (knowledge graph)| โŒ CLI only |
| **Fetch** | โŒ N/A | โŒ N/A | โŒ N/A | โš ๏ธ Check | โœ… Works (manual) | โŒ CLI only |
| **Figma** | โŒ N/A | โŒ N/A | โŒ N/A | โš ๏ธ Check | โŒ Not configured | โœ… 5 tools |
| **Slack** | โŒ N/A | โŒ N/A | โŒ N/A | โš ๏ธ Check | โŒ Not configured | โœ… 7 tools |
| **Stripe** | โŒ N/A | โŒ N/A | โŒ N/A | โš ๏ธ Check | โŒ Not configured | โœ… 9 tools |
**Legend:**
- โœ… Works = Fully functional
- โŒ Hangs = Will cause hang/timeout
- โŒ N/A = Not available/configured
- โš ๏ธ Check = Verify before using
---
### Editor-Specific Configuration
#### Antigravity Editor
**Full MCP Support dengan catatan model:**
```markdown
Antigravity + Gemini 3:
โ”œโ”€ โœ… ALL 6 MCP servers available
โ”œโ”€ โœ… External API MCP works (GitHub, Firebase, Cloud Run, Dart)
โ”œโ”€ โœ… Local MCP works (Redis, Sequential Thinking)
โ””โ”€ โœ… Recommended untuk MCP-heavy workflows
Antigravity + Claude Sonnet:
โ”œโ”€ โœ… Local MCP only (Redis, Sequential Thinking)
โ”œโ”€ โŒ External API MCP HANGS (GitHub, Firebase, Cloud Run, Dart)
โ”œโ”€ โœ… Use CLI alternatives (git, firebase, gcloud, flutter)
โ””โ”€ โœ… Recommended untuk code analysis (no MCP needed)
```
#### VSCode + GitHub Copilot
**Limited MCP - GitHub only:**
```markdown
Available Tools:
โ”œโ”€ โœ… github-pull-request_activePullRequest()
โ”œโ”€ โœ… github-pull-request_issue_fetch()
โ”œโ”€ โœ… github-pull-request_openPullRequest()
โ”œโ”€ โœ… github-pull-request_doSearch()
โ”œโ”€ โœ… Workspace management tools
โ””โ”€ โœ… API request tools
Not Available:
โ”œโ”€ โŒ Firebase MCP
โ”œโ”€ โŒ Cloud Run MCP
โ”œโ”€ โŒ Dart MCP
โ”œโ”€ โŒ Redis MCP
โ””โ”€ โŒ Sequential Thinking MCP
```
**Workaround:** Use terminal commands untuk access services
#### Cursor AI
**Flexible MCP Support dengan Agent Mode:**
```markdown
Cursor Capabilities:
โ”œโ”€ โœ… Agent Mode (default) - Combines Chat, Composer, and Agent
โ”œโ”€ โœ… Built-in tools (file ops, terminal, code completion)
โ”œโ”€ โœ… Rules system (.cursor/rules.md or .mdc files)
โ”œโ”€ โœ… Web search (automatic, no explicit command)
โ”œโ”€ โœ… /Generate Cursor Rules command (from conversation)
โ””โ”€ โš ๏ธ MCP servers (configurable via workspace settings)
MCP Configuration:
โ”œโ”€ โš ๏ธ Status depends on user workspace setup
โ”œโ”€ โš ๏ธ Requires manual configuration in Cursor settings
โ”œโ”€ โš ๏ธ Test each MCP before heavy use
โ””โ”€ โœ… CLI fallbacks available when MCP unavailable
Workflow Priority:
1. Built-in Cursor tools (primary)
2. Project Rules (.cursor/rules.md)
3. MCP Servers (if configured)
4. CLI fallbacks (backup)
```
**Configuration:**
- Rules: `.cursor/rules.md` (enhanced) or `.cursor/rules/*.mdc` files
- MCP: Cursor Settings โ†’ MCP Servers (workspace-specific)
- User Rules: Global settings (applied to all projects)
- Agent Mode: Default since Feb 2025 update
#### Kiro AI
**Full MCP Support dengan 18 servers (12 active):**
```markdown
Kiro Capabilities:
โ”œโ”€ โœ… 18 MCP servers total (12 active, 6 disabled)
โ”œโ”€ โœ… Built-in tools (file ops, terminal, diagnostics)
โ”œโ”€ โœ… Kiro Powers (subagents: context-gatherer, general-task-execution)
โ”œโ”€ โœ… Auto-approve untuk read operations
โ””โ”€ โœ… Recommended untuk multi-tool workflows
Active MCP Servers (12):
โ”œโ”€ Database: mysql, sqlite
โ”œโ”€ Automation: git, filesystem, chrome-devtools, puppeteer
โ”œโ”€ Analysis: lighthouse, sequential-thinking, memory
โ”œโ”€ Network: fetch
โ””โ”€ Utility: time, everything
Disabled Servers (6):
โ”œโ”€ aws, sentry, jira, figma (need credentials)
โ””โ”€ youtube-transcript, playwright (package not found)
Workflow Priority:
1. Built-in Kiro tools (primary)
2. Kiro Powers (when available)
3. MCP Servers (parallel execution)
4. CLI fallbacks (backup)
```
**Steering Files (Always Included):**
- `structure.md` - File organization rules
- `tech.md` - Tech stack & capabilities
- `efficiency.md` - Efficiency guidelines
- `product.md`, `security.md` - Additional guidelines
**Configuration:**
- MCP config: `.kiro/settings/mcp.json` (workspace-specific)
- Rules: `.kiro/rules.md` (enhanced with 18 MCP servers)
- Steering: `.kiro/steering/*.md` (auto-included)
---
#### Windsurf Editor
**Advanced AI dengan Cascade & Memories:**
```markdown
Windsurf Capabilities:
โ”œโ”€ โœ… Cascade AI (GPT-5.1) - Advanced reasoning
โ”œโ”€ โœ… Memories (48h learning) - Pattern recognition
โ”œโ”€ โœ… MCP Support (21 tools) - Figma, Slack, Stripe
โ”œโ”€ โœ… Drag & Drop Images - Design-to-code
โ”œโ”€ โœ… Terminal Command - Natural language CLI
โ”œโ”€ โœ… Lint Fixing - Auto-fix 60% success rate
โ””โ”€ โœ… Continue My Work - Session persistence
MCP Tools Available:
โ”œโ”€ Design: Figma (5 tools)
โ”œโ”€ Communication: Slack (7 tools)
โ”œโ”€ Payment: Stripe (9 tools)
โ””โ”€ Reasoning: Sequential Thinking (3 tools)
Workflow Priority:
1. Cascade AI (primary) - Built-in GPT-5.1
2. Memories (context) - Learned patterns
3. MCP Tools (21 available) - Third-party integrations
4. CLI Fallback (backup) - Manual operations
```
**Configuration:**
- Rules: `.windsurf/rules.md` (editor-specific)
- MCP: Windsurf Settings โ†’ MCP Servers (one-click setup)
- Memories: Auto-learn after 48h analysis
- AI Model: Cascade (GPT-5.1/GPT-5.1-Codex)
**Unique Features:**
- **Memories Learning:** 78% pattern consistency for 50K+ line projects
- **Lint Fixing:** Real-time ESLint/Prettier auto-fix
- **Drag & Drop:** Generate React from images/Figma
- **Turbo Mode:** Auto-execute terminal commands
---
### ๐ŸŽฏ Quick Decision Guide
**"Which model/editor should I use for this task?"**
| Task | Best Choice | Reason |
|---------------------------|----------------------|--------------------------------------|
| **GitHub PR operations** | Antigravity + Gemini | Full GitHub MCP |
| **Firebase deployment** | Antigravity + Gemini | Firebase MCP required |
| **Cloud Run deploy** | Antigravity + Gemini | Cloud Run MCP required |
| **Flutter development** | Antigravity + Gemini | Dart MCP required |
| **Code analysis/review** | Any Claude model | Superior reasoning |
| **Local caching** | Any model | Redis MCP works everywhere |
| **Complex reasoning** | Any model | Sequential Thinking works everywhere |
| **Simple git operations** | Any editor | `git` CLI sufficient |
| **Quick PR review** | VSCode Copilot | Built-in PR tools |
| **Multi-file refactoring** | โœ… Cursor | Composer mode for batch changes |
| **Code completion** | โœ… Cursor | Superior inline editing & autocomplete|
| **Rules from conversation** | โœ… Cursor | /Generate Cursor Rules command |
| **Multi-tool workflows** | โœ… Kiro | 12 active MCP servers, built-in tools |
| **Database operations** | โœ… Kiro | MySQL/SQLite MCP with auto-approve |
| **Browser automation** | โœ… Kiro | Chrome DevTools + Puppeteer MCP |
| **Performance audit** | โœ… Kiro | Lighthouse MCP (auto-approve) |
| **Knowledge graph** | โœ… Kiro | Memory MCP for context management |
| **Design-to-code** | โœ… Windsurf | Figma MCP + Drag & Drop Images |
| **Payment integration** | โœ… Windsurf | Stripe MCP (9 tools) |
| **Team notifications** | โœ… Windsurf | Slack MCP (7 tools) |
| **Pattern learning** | โœ… Windsurf | Memories feature (48h learning) |
| **Natural language CLI** | โœ… Windsurf | Terminal Command (80% success) |
---
### ๐Ÿ”„ MCP Fallback Strategy
Jika MCP tidak tersedia atau hang, gunakan CLI alternatives:
```bash
# โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•
# FALLBACK: CLI Alternatives untuk MCP
# โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•
# โ”€โ”€ GitHub (instead of GitHub MCP) โ”€โ”€
git status
git log -n 10
git push origin main
gh pr list
gh pr create
gh issue list
# โ”€โ”€ Firebase (instead of Firebase MCP) โ”€โ”€
firebase login --reauth
firebase projects:list
firebase deploy
firebase deploy --only hosting
firebase deploy --only functions
# โ”€โ”€ Cloud Run (instead of Cloud Run MCP) โ”€โ”€
gcloud auth login
gcloud projects list
gcloud run services list
gcloud run deploy SERVICE_NAME --source .
# โ”€โ”€ Dart/Flutter (instead of Dart MCP) โ”€โ”€
flutter doctor
flutter devices
flutter run
flutter run -d chrome
flutter build apk
flutter test
# โ”€โ”€ Redis (if Redis MCP unavailable) โ”€โ”€
redis-cli ping
redis-cli SET key "value"
redis-cli GET key
redis-cli KEYS "pattern:*"
```
---
### โš ๏ธ Pre-Session MCP Check Protocol
**Sebelum mulai session baru, AI agent HARUS:**
```markdown
1. [ ] Identify current editor (Antigravity/VSCode/Cursor/Kiro)
2. [ ] Identify active model (Gemini/Claude/GPT)
3. [ ] Check MCP compatibility matrix above
4. [ ] For task requiring external MCP:
- If Claude: Use CLI fallback or switch to Gemini
- If Gemini: Proceed with MCP
- If unsure: Test simple MCP call first (Redis SET/GET)
5. [ ] Warn user if MCP incompatibility detected
```
**Example Warning Message:**
```markdown
โš ๏ธ **MCP Compatibility Notice**
Anda menggunakan Claude Sonnet. Task ini memerlukan GitHub MCP
yang tidak compatible dengan Claude.
**Options:**
1. Switch ke Gemini 3 model
2. Saya gunakan `git` CLI sebagai alternatif
Pilih opsi yang diinginkan?
```
---
## โšก Database Performance
> Berdasarkan benchmark 2026-01-04
### Hasil Benchmark
| Database | PHP Library | CLI Tool | Difference |
|------------|--------------|----------------|-----------------|
| **MySQL** | PDO: 3.20ms | mysql: ~75ms | **23x faster** |
| **Oracle** | OCI8: 2.25ms | SQLPlus: 355ms | **157x faster** |
### Guidelines
**โœ… SELALU gunakan PHP libraries untuk aplikasi:**
```php
// MySQL - PDO (recommended)
$pdo = new PDO('mysql:host=127.0.0.1;port=3306;dbname=db', 'root', '');
// Oracle - OCI8
$conn = oci_connect('user', 'pass', '//localhost:1521/ORCL');
```
**โš ๏ธ CLI tools hanya untuk admin tasks:**
```bash
# OK untuk interactive/one-off
mysql -h 127.0.0.1 -u root
sqlplus user/pass@ORCL
```
**โŒ JANGAN gunakan CLI dalam loops:**
```php
// SALAH - 157x lebih lambat!
for ($i = 0; $i < 100; $i++) {
exec("sqlplus user/pass@ORCL @query.sql");
}
```
### Connection Info
| Database | Host | Port | User | Notes |
|----------|-----------|------|---------|------------------------------------------|
| MySQL | 127.0.0.1 | 3306 | root | Password kosong |
| Oracle | localhost | 1521 | testphp | Password: testphp123 |
> ๐Ÿ“š **Detail:** `.agent/memory/entries/decisions/php-libraries-over-cli-tools.md`
---
## ๐ŸŽจ Web Apps UI/UX Guidelines
### Design Principles
- **Mobile-first** approach untuk semua development
- **Accessibility** compliance (WCAG 2.1)
- **Performance-oriented** design (Core Web Vitals)
- **Consistent** design system dengan reusable components
### CSS Best Practices
| Guideline | Example |
|-----------|---------|
| Use CSS Variables | `var(--primary-color)` |
| BEM Naming | `.card__title--active` |
| Mobile-first queries | `@media (min-width: 768px)` |
| Prefer flexbox/grid | Hindari float layouts |
```css
/* โœ… BENAR - CSS Variables + Modern Layout */
:root {
--primary: #3b82f6;
--radius: 0.5rem;
}
.card {
display: grid;
gap: 1rem;
border-radius: var(--radius);
}
```
### JavaScript Guidelines
- **ES6+** features (arrow functions, destructuring, modules)
- **async/await** over callbacks
- **Event delegation** untuk dynamic content
- **Lazy loading** untuk performance
```javascript
// โœ… BENAR - Modern JS Pattern
const loadData = async () => {
const { data } = await fetch('/api/items').then(r => r.json());
return data;
};
```
### UI Framework Recommendations
| Project Type | Recommended Framework |
|--------------|----------------------|
| Simple landing | Vanilla CSS + JS |
| Medium webapp | Bootstrap 5 / TailwindCSS |
| Complex SPA | React / Vue + CSS-in-JS |
| E-commerce | Next.js / Nuxt.js |
### Browser Testing Checklist
- [ ] Chrome, Firefox, Safari, Edge
- [ ] Mobile: iOS Safari, Chrome Android
- [ ] Lighthouse score โ‰ฅ 90
- [ ] No console errors
---
## ๐Ÿš€ Node.js/PM2 Service Management
> Untuk project microservices dengan Kafka, Express, atau API services
### PM2 Quick Commands
```bash
# Start services
pm2 start ecosystem.config.js
pm2 start ecosystem.config.js --only service-name
# Stop/Restart
pm2 stop service-name
pm2 restart all
pm2 reload service-name # Zero-downtime reload
# Monitoring
pm2 list
pm2 monit
pm2 logs
pm2 logs service-name --lines 100
pm2 logs --err --lines 50 # Errors only
# Persist & Auto-start
pm2 save
pm2 startup
```
### โš ๏ธ Critical: Kafka Consumer Rules
```javascript
// ecosystem.config.js
{
name: 'kafka-consumer',
instances: 1, // โš ๏ธ NEVER > 1! Causes message duplication
exec_mode: 'fork', // NOT cluster!
}
```
**Why?** Multiple Kafka consumers in same group cause message duplication due to partition rebalancing.
### API Instances (Can Scale)
```javascript
{
name: 'api-server',
instances: 2, // Can scale as needed
exec_mode: 'cluster' // Load balanced
}
```
### Portable Deployment Checklist
```
โœ… WAJIB COPY:
โ”œโ”€โ”€ package.json, package-lock.json
โ”œโ”€โ”€ .env.example (NOT .env!)
โ”œโ”€โ”€ ecosystem.config.js
โ”œโ”€โ”€ src/**/*.js
โ””โ”€โ”€ database/schema.sql
โŒ JANGAN COPY:
โ”œโ”€โ”€ node_modules/ (npm install ulang)
โ”œโ”€โ”€ .env (buat baru di server)
โ”œโ”€โ”€ logs/
โ””โ”€โ”€ .git/
```
> ๐Ÿ“š **Detail:** `.agent/memory/entries/patterns/pm2-ecosystem-startup-pattern.md`
---
## ๐Ÿ“ฑ Mobile Development (Android/Flutter)
### Flutter Environment
- **Flutter SDK:** Path verified in `.agent/context/environment.json`
- **Android Studio:** Emulator & SDK Support
- **MCP Server:** `dart-mcp-server` available
### Quick Commands
```bash
# Create new project
flutter create my_app
# Run on device/emulator
flutter run
# Build release APK
flutter build apk --release
# Analyze & format code
flutter analyze
dart format .
# Run tests
flutter test
```
### Flutter Best Practices
| Practice | Description |
|----------|-------------|
| **const constructors** | Use const untuk widget statis |
| **State management** | BLoC/Provider/Riverpod |
| **Null safety** | Handle null dengan `?` dan `!` |
| **Widget extraction** | Split ke files terpisah |
```dart
// โœ… BENAR - Const + Clean Structure
class ProductCard extends StatelessWidget {
const ProductCard({super.key, required this.product});
final Product product;
@override
Widget build(BuildContext context) {
return const Card(child: ...);
}
}
```
### Project Structure
```
lib/
โ”œโ”€โ”€ main.dart
โ”œโ”€โ”€ models/ # Data models
โ”œโ”€โ”€ screens/ # Full page widgets
โ”œโ”€โ”€ widgets/ # Reusable components
โ”œโ”€โ”€ services/ # API, database
โ””โ”€โ”€ utils/ # Helpers, constants
```
### MCP Dart Tools Available
| Tool | Fungsi |
|------|--------|
| `launch_app` | Launch Flutter app |
| `hot_reload` | Apply code changes |
| `hot_restart` | Restart app state |
| `get_widget_tree` | Inspect widget hierarchy |
| `run_tests` | Execute Flutter tests |
| `flutter_driver` | UI automation |
---
## ๐Ÿ“ Responsive Design & Accessibility
### Breakpoints (Bootstrap 5)
| Breakpoint | Size | Target Device |
|------------|------|---------------|
| xs | <576px | Mobile portrait |
| sm | โ‰ฅ576px | Mobile landscape |
| md | โ‰ฅ768px | Tablet |
| lg | โ‰ฅ992px | Desktop |
| xl | โ‰ฅ1200px | Large desktop |
| xxl | โ‰ฅ1400px | Extra large |
### Media Query Pattern
```css
/* Mobile first - base styles untuk mobile */
.container { padding: 1rem; }
/* Tablet ke atas */
@media (min-width: 768px) {
.container { padding: 2rem; }
}
/* Desktop ke atas */
@media (min-width: 1024px) {
.container { max-width: 1200px; }
}
```
### Accessibility Checklist (WCAG 2.1)
| Requirement | Implementation |
|-------------|----------------|
| **Alt text** | Semua `<img>` punya `alt` |
| **Color contrast** | Ratio โ‰ฅ 4.5:1 |
| **Keyboard nav** | `tabindex`, focus states |
| **ARIA labels** | Interactive elements |
| **Focus indicator** | Visible `:focus` styles |
```html
<!-- โœ… BENAR - Accessible Button -->
<button
aria-label="Close dialog"
class="btn-close"
tabindex="0">
<span aria-hidden="true">&times;</span>
</button>
```
---
## ๐Ÿงช Testing Strategy
> **๐Ÿ“ Test Location:** `test/` - Lihat [`test/README.md`](test/README.md) untuk panduan lengkap.
### Project Test Structure
```
test/
โ”œโ”€โ”€ database/ โ† Database testing (Oracle, MySQL, benchmarks)
โ”œโ”€โ”€ server/ โ† Server-side testing (PHP, Redis, HTTP)
โ”œโ”€โ”€ python/ โ† Python testing (pytest, unit tests)
โ””โ”€โ”€ temp/ โ† Temporary test files (not committed)
```
### Testing Levels
| Type | Tools | Location | When to Run |
|------|-------|----------|-------------|
| **Unit** | pytest, PHPUnit | `test/python/`, `test/server/` | Setiap commit |
| **Database** | PHP PDO/OCI8 | `test/database/` | Sebelum deploy |
| **Integration** | Postman, Cypress | - | Setiap PR |
| **E2E** | Playwright, Selenium | - | Before release |
### Quick Test Commands
```bash
# Python Tests
cd test/python && pytest -v
# Database Tests
php test/database/oracle/test-oracle-final.php
php test/database/mysql/test-mysql-connection.php
# Server Tests
php test/server/redis-test.php
php test/server/mysql-test.php
# Benchmarks
php test/database/benchmarks/benchmark-mysql-access.php
```
### ๐Ÿค– AI Agent Test Guidelines
1. **Python tests** โ†’ `test/python/test_*.py`
2. **PHP database tests** โ†’ `test/database/<db_name>/`
3. **PHP server tests** โ†’ `test/server/`
4. **Temporary files** โ†’ `test/temp/` (auto-cleanup)
> โš ๏ธ **JANGAN buat test files di ROOT!** Selalu gunakan struktur `test/` di atas.
---
## ๐Ÿž Debugging & Troubleshooting Patterns
> **NEW:** Comprehensive debugging guides for all platforms.
| Platform | Pattern File | Key Capabilities |
|----------|--------------|------------------|
| **Python** | [python-debug-workflow.md](.agent/memory/entries/patterns/python-debug-workflow.md) | `pdb`, logging, traceback, automation |
| **PowerShell** | [powershell-debug-pattern.md](.agent/memory/entries/patterns/powershell-debug-pattern.md) | Error handling, strict mode, script debug |
| **Browser** | [browser-devtools-integration.md](.agent/memory/entries/patterns/browser-devtools-integration.md) | Console logs, network inspection, overlays |
| **Node.js** | [nodejs-debug-pattern.md](.agent/memory/entries/patterns/nodejs-debug-pattern.md) | `--inspect`, PM2 logs, async error handling |
### Quick Debug Checklist
1. **Python**: Gunakan `python script.py` jangan `python -c` multiline.
2. **PowerShell**: Set `$ErrorActionPreference = "Stop"` di awal script.
3. **Browser**: Gunakan `browser_subagent` untuk capture console logs.
4. **Node.js**: Cek `pm2 logs --err` untuk production errors.
---
## ๐Ÿง  Memory System
Agent memiliki akses ke knowledge base di `.agent/memory/`.
### Available Scripts:
| Script | Fungsi |
|--------|--------|
| `save-knowledge.py` | Simpan knowledge baru (dengan duplicate detection) |
| `search-knowledge.py` | Cari knowledge by keyword/tag/category |
| `validate-index.py` | Validasi & fix index consistency |
| `backup-memory.py` | Backup/restore (ZIP compressed, auto-timestamp) |
| `detect-environment.py` | Deteksi environment project |
| `sync-agents-stats.py` | Auto-sync statistics di AGENTS.md |
### Kategori Memory:
- **gotchas/** - Production bugs & fixes (๐Ÿšจ CRITICAL)
- **patterns/** - Code patterns yang works
- **decisions/** - Architectural decisions
- **context/** - Project guides & references
### Cari Knowledge:
- **Via Script:** `python .agent/.agent/scripts/search-knowledge.py "keyword"`
- **Manual:** Cek `.agent/memory/index.json` untuk daftar semua entries
### Backup:
Semua backup tersimpan di `_backups/` dengan format `memory_backup_YYYYMMDD_HHMMSS.zip`.
---
## ๐Ÿ“ Project Structure
```
project-root/
โ”œโ”€โ”€ AGENTS.md โ† Entry point (You are here)
โ”œโ”€โ”€ .github/
โ”‚ โ””โ”€โ”€ copilot-instructions.md โ† GitHub Copilot support
โ”œโ”€โ”€ .cursor/
โ”‚ โ””โ”€โ”€ rules.md โ† Cursor AI support
โ”œโ”€โ”€ .kiro/
โ”‚ โ””โ”€โ”€ rules.md โ† Kiro AI support
โ”œโ”€โ”€ .agent/
โ”‚ โ”œโ”€โ”€ memory/ โ† Knowledge persistence
โ”‚ โ”‚ โ”œโ”€โ”€ index.json โ† Searchable index
โ”‚ โ”‚ โ””โ”€โ”€ entries/
โ”‚ โ”‚ โ”œโ”€โ”€ gotchas/ โ† Critical bugs
โ”‚ โ”‚ โ”œโ”€โ”€ patterns/ โ† Code patterns
โ”‚ โ”‚ โ”œโ”€โ”€ decisions/ โ† Arch decisions
โ”‚ โ”‚ โ””โ”€โ”€ context/ โ† Project guides
โ”‚ โ”œโ”€โ”€ context/ โ† Environment detection
โ”‚ โ””โ”€โ”€ workflows/ โ† AI workflows
โ”œโ”€โ”€ scripts/ โ† Automation scripts
โ””โ”€โ”€ _backups/ โ† Auto-compressed backups
```
---
## ๐Ÿ”— Related Files
- [Memory Index](./.agent/memory/index.json)
- [Project Context](./.agent/context/project-context.json)
- [Session Init](./.agent/context/session-init.md)
---
## ๐Ÿš€ Session Initialization Protocol
**UNTUK AI AGENT:** Saat membuka project ini, WAJIB baca file-file berikut:
### 1. Critical Files (MUST READ!)
```
.agent/context/session-init.md โ† Initialization protocol
.agent/context/project-context.json โ† Project info
.agent/memory/index.json โ† Knowledge index
.agent/memory/entries/gotchas/*.md โ† Critical gotchas
```
### 2. Auto-Load Behavior
AI agent akan otomatis:
- โœ… Load project context & environment
- โœ… Load semua critical gotchas
- โœ… Load top 5 patterns yang sering dipakai
- โœ… Siap bekerja tanpa perlu dijelaskan ulang
### 3. End of Session Protocol
Sebelum session berakhir:
- โœ… Simpan semua learnings baru
- โœ… Update memory index
- โœ… Buat summary report
**Detail lengkap:** Lihat `.agent/workflows/cara-simpan-pengetahuan-dari-chat.md`
---
*Last Updated: 2026-01-07*
*Stats auto-sync: `python .agent/.agent/scripts/sync-agents-stats.py`*