AI coding agent lokal yang berjalan di desktop (seperti aplikasi berbasis Electron) membutuhkan context file, prompt templates, dan definisi tool yang terstruktur agar dapat bekerja secara optimal. Jika developer memperbarui konfigurasi tanpa validasi ketat, prompt template yang rusak atau path file konteks yang mengarah ke file non-eksisten akan memicu halusinasi model, konsumsi token berlebih, atau kegagalan eksekusi tool di mesin lokal.

Solusinya adalah menerapkan automasi CI validasi context file untuk AI coding agent. Pipeline ini memastikan kontrak skema ditaati, semua referensi file lokal valid di dalam repositori, dan tool payload dapat diproses dengan benar sebelum perubahan di-merge ke branch utama.

1. Desain Kontrak Skema Konfigurasi Agent

Definisikan konfigurasi agen dalam format JSON atau YAML yang mencakup metadata template, referensi path konteks kode, dan definisi tool. Validasi kontrak data ini menggunakan JSON Schema standard (Draft 7 atau Draft 2020-12).

Struktur file konfigurasi target (agent.config.json):

{
  "version": "1.0.0",
  "prompt_template": "Prompts/code-refactor.md",
  "context_files": [
    "src/core/parser.ts",
    "docs/architecture.md"
  ],
  "tools": [
    {
      "name": "run_linter",
      "command": "npm run lint",
      "timeout_ms": 5000
    }
  ]
}

Skema JSON untuk validasi struktural (schemas/agent-config.schema.json):

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "AgentConfig",
  "type": "object",
  "required": ["version", "prompt_template", "context_files", "tools"],
  "additionalProperties": false,
  "properties": {
    "version": { "type": "string" },
    "prompt_template": { "type": "string" },
    "context_files": {
      "type": "array",
      "items": { "type": "string" },
      "minItems": 1
    },
    "tools": {
      "type": "array",
      "items": {
        "type": "object",
        "required": ["name", "command"],
        "properties": {
          "name": { "type": "string" },
          "command": { "type": "string" },
          "timeout_ms": { "type": "integer", "minimum": 1000 }
        }
      }
    }
  }
}

2. Script Linter: Validasi Skema dan Integritas Path

Skema JSON standar tidak memvalidasi keberadaan file di disk. Kita memerlukan script linter berbasis Node.js yang memverifikasi dua hal:

  1. Kesesuaian payload terhadap skema (menggunakan engine seperti ajv).
  2. Integritas path file yang direferensikan pada disk nyata (prompt template dan context files).

Simpan script berikut di scripts/validate-agent-config.js:

const fs = require('fs');
const path = require('path');
const Ajv = require('ajv');

const ajv = new Ajv({ allErrors: true });
const ROOT_DIR = process.cwd();

function validate() {
  const configPath = path.join(ROOT_DIR, 'agent.config.json');
  const schemaPath = path.join(ROOT_DIR, 'schemas/agent-config.schema.json');

  if (!fs.existsSync(configPath)) {
    console.error(`ERROR: Config file tidak ditemukan di: ${configPath}`);
    process.exit(1);
  }

  const config = JSON.parse(fs.readFileSync(configPath, 'utf8'));
  const schema = JSON.parse(fs.readFileSync(schemaPath, 'utf8'));

  // 1. Validasi Skema Struktur
  const validateSchema = ajv.compile(schema);
  const valid = validateSchema(config);
  if (!valid) {
    console.error('ERROR: Schema validation failed:');
    console.error(validateSchema.errors);
    process.exit(1);
  }

  // 2. Validasi Keberadaan Path File
  const filesToCheck = [config.prompt_template, ...config.context_files];
  const missingFiles = [];

  for (const relativePath of filesToCheck) {
    const absolutePath = path.resolve(ROOT_DIR, relativePath);
    if (!fs.existsSync(absolutePath)) {
      missingFiles.push(relativePath);
    }
  }

  if (missingFiles.length > 0) {
    console.error('ERROR: Path context file berikut tidak ditemukan di disk:');
    missingFiles.forEach(f => console.error(` - ${f}`));
    process.exit(1);
  }

  console.log('Validasi context file dan schema agent lolos.');
}

validate();

3. Smoke Test Eksekusi Mock Agent

Untuk memastikan context file dapat dimuat ke memori tanpa melampaui batasan ukuran buffer yang dialokasikan runtime agent lokal (misalnya Electron IPC payload limit), jalankan smoke test mock loader sederhana di runner CI.

Simpan di scripts/mock-agent-runner.js:

const fs = require('fs');
const path = require('path');

const MAX_FILE_SIZE_BYTES = 500 * 1024; // Limit 500KB per context file
const config = JSON.parse(fs.readFileSync('agent.config.json', 'utf8'));

for (const file of config.context_files) {
  const stat = fs.statSync(file);
  if (stat.size > MAX_FILE_SIZE_BYTES) {
    console.error(`ERROR: File konteks ${file} (${stat.size} bytes) melebihi batas ${MAX_FILE_SIZE_BYTES} bytes.`);
    process.exit(1);
  }
  
  const content = fs.readFileSync(file, 'utf8');
  if (content.trim().length === 0) {
    console.error(`ERROR: File konteks ${file} kosong.`);
    process.exit(1);
  }
}

console.log('Smoke test loader mock agent berhasil.');

4. Workflow CI Menggunakan GitHub Actions

Integrasikan script validasi dan smoke test ke dalam GitHub Actions agar commit atau Pull Request yang melanggar kontrak konfigurasi langsung digagalkan (fail-fast).

Buat workflow file di .github/workflows/validate-agent.yml:

name: Validate Agent Context and Tools

on:
  pull_request:
    paths:
      - 'agent.config.json'
      - 'schemas/**'
      - 'Prompts/**'
      - 'src/**'
  push:
    branches:
      - main

jobs:
  lint-and-test:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repository
        uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: 'npm'

      - name: Install Dependencies
        run: npm ci

      - name: Validate Schema and File Integrity
        run: node scripts/validate-agent-config.js

      - name: Run Mock Agent Smoke Test
        run: node scripts/mock-agent-runner.js

5. Trade-off dan Troubleshooting

Saat menerapkan validasi CI ini, pertimbangkan batasan dan kesalahan umum berikut:

  • Case Sensitivity OS: Developer di macOS atau Windows sering kali menggunakan path case-insensitive (misal: prompts/main.md vs Prompts/main.md). Runner Linux di GitHub Actions bersifat case-sensitive. Script linter akan gagal jika ada mismatch huruf besar/kecil.
  • Ukuran Repository Bloat: Menaruh context file statis berukuran besar langsung di repo dapat memperlambat checkout CI. Gunakan batasan ukuran file pada smoke test untuk mencegah context poisoning.
  • Alternative Lazier: Jika tidak ingin mengelola script Node.js custom, gunakan CLI standard seperti check-json-schema dan bash test -f via GitHub Action run step langsung. Script custom tetap disarankan jika aturan validasi mencakup inspeksi konteks multi-field.