Prompt Engineering in Jcode

Jcode's philosophy is that the harness matters as much as the model. Its base system prompt shrank 73% since v0.1 (2,476 → 659 tokens) because frontier models got better at following simple instructions — and jcode puts procedure in tools and memory rather than the prompt. Your job is to give the agent goals it can measure, not step-by-step scripts.

AGENTS.md — The System Prompt

AGENTS.md at repo root and ~/AGENTS.md globally are loaded into every session. Keep it dense and conventions-focused — jcode already knows how to edit files and run commands:

# AGENTS.md

## Commands
- `npm run dev` — Start dev server (Next.js, port 3000)
- `npm run build` — Production build (type check, lint, bundle)
- `npx vitest run` — Run all tests
- `npx eslint .` — Lint check

## Architecture
- Next.js 15 App Router, React Server Components by default
- TypeScript strict, path alias `@/`
- SQLite via better-sqlite3 — no ORM, raw SQL

## Conventions
- Co-locate tests: `foo.spec.ts` next to `foo.ts`
- kebab-case components, camelCase utilities
- Server components by default; `'use client'` only for interactivity

Hill-Climbable Goals

Jcode's most distinctive prompting concept. Every agent goal receives a hill-climbability rating from 0 to 100, based on how quantifiable and iterable the progress is. When a goal scores low, the harness pushes back and asks you to reframe it into a verifiable objective with a measurable signal.

Low hill-climbability (jcode will push back):

Improve the performance of the API.

High hill-climbability:

Make the /api/orders endpoint respond in under 150ms p95
for 10k-order users. Use k6 to benchmark before and after,
and keep all existing tests green. Report before/after numbers.

The measurable metric gives the agent a feedback loop to iterate against — the same mechanism RL models train on. 91% of real goals jcode observed scored above the hill-climbability gate; the ones below it are where agents stall.

Todo Discipline

Jcode's todo tool asks the agent to rate its confidence in each task item — at assignment and when marked done. The pattern from real Terminal-Bench runs: agents are confident after a task, but a low confidence at assignment is real signal. When jcode sees a large spike (low at assignment → 100 at done), it forces the agent to go back and check its work.

Use /todos to surface the todo list as a card in the chat. Break work into items the agent can validate independently:

Build a checkout flow. Todos:
1. Add Stripe checkout session endpoint (confidence 0.9)
2. Add client-side redirect to Stripe (confidence 0.8)
3. Add webhook handler for payment confirmation (confidence 0.6 — needs
   verification against Stripe test events)
4. Add success/cancel pages (confidence 0.95)

The low-confidence items are where you should expect jcode to double back and verify.

Auto-Poke: Persistence

Most agent failures aren't wrong answers — they're early exits. Models love to declare victory. Jcode checks the todo list first: when a turn ends with incomplete todos, the harness pokes the model back to work automatically. Transient network errors are retried; non-retryable errors stop the loop instead of burning tokens.

You don't need to say "keep going until done." Just leave todos incomplete and jcode keeps iterating. This also powers headless jcode run sessions, which keep working across turns until the work is finished.

Prompt Patterns for Jcode

Pattern 1: The Measurable Refactor

Refactor the auth middleware. Target: reduce token processing
time by 50% on the /api/* routes. Baseline is in
perf/bench-auth.ts — run it before and after, and update
perf/results.md with both numbers. Do not touch behavior.

Pattern 2: Parallel Task Fan-Out

Jcode is built for parallelism. Split work into independent pieces and let swarms run them concurrently:

Refactor these four modules into independent tasks:
- src/auth → task 1
- src/billing → task 2
- src/notifications → task 3
- src/search → task 4
Each: extract pure logic into lib/, keep public API identical,
run the module's tests. Report each task's results separately.

Pattern 3: Review with Layered Verification

/review and /test launch one-shot sessions that verify claims with layered tests:

/review
Review the new rate-limiting middleware for:
- Race conditions on the token bucket
- Header spoofing (X-Forwarded-For)
- Off-by-one on the limit window
Write a failing test for each issue you find, then fix them.

Pattern 4: Memory-Contextual Work

Because jcode recalls related memories automatically, you can lean on prior decisions:

We decided last sprint to use TTL-based cache invalidation in
billing. Implement the same pattern for the new /usage endpoint,
and note any places where the memory differs from current code.

Common Pitfalls

Over-scripting

Step 1: open the file. Step 2: find the function. Step 3: change line 42...

Jcode already knows how to work. Give it the goal and the verification signal, not a macro.

Unmeasurable acceptance criteria

Make the UI nicer.   ← Low hill-climbability, jcode will push back

Match the design tokens in design/tokens.json, pass the a11y
check in tests/a11y, keep Lighthouse CLS < 0.1.   ← Measurable

Empty todo lists

Leave todos populated. Auto-poke and confidence stepping only work when there's a checklist to check.

Ignoring memory

Jcode's memory injects relevant past context automatically. Don't re-explain established project decisions — reference them and let recall fill the gaps.

Related Pages

• Jcode Getting Started — Installation and provider setup
• Jcode Configuration Reference — config.toml, MCP, memory, remote
• Memory, Swarms & Self-Dev — advanced workflows
• Agent Skills (Agents Section) — cross-tool SKILL.md standard
• Prompt Chaining (Prompts Section) — multi-step prompt patterns