Practical notes: Your Coding Agent Doesn’t Need a Better Prompt

The following notes reconstruct a practical path around “Your Coding Agent Doesn’t Need a Better Prompt”. Emphasis stays on contracts, checks, and drop-in code placeholders rather than motivational framing.

It Needs Better Working Conditions

When working through the It Needs Better Working stage, write down the contract first: required inputs, success signal, and what happens on partial failure. That checklist keeps later code changes honest. Keep configuration outside application code. Environment files, secret stores, and feature flags belong in one place operators can audit without reading the whole graph. Cache stable system instructions and tool schemas. Re-sending identical preamble is a common source of burn.

The curl loop

When working through the The curl loop stage, write down the contract first: required inputs, success signal, and what happens on partial failure. That checklist keeps later code changes honest. Document the happy path and the recovery path together. Retries, human gates, and dead-letter handling are part of the product, not later polish. Cache stable system instructions and tool schemas. Re-sending identical preamble is a common source of burn.

search for artifact
      ↓
try dependency
      ↓
Maven failure
      ↓
search web
      ↓
curl documentation
      ↓
download JAR
      ↓
inspect classes
      ↓
try another version
      ↓
search again

Iteration 1: Fix the environment

When working through the Iteration 1 Fix the stage, write down the contract first: required inputs, success signal, and what happens on partial failure. That checklist keeps later code changes honest. Prefer small, testable units over sprawling scripts. When a step fails, the failure should point at a single responsibility rather than a tangled pipeline. Cache stable system instructions and tool schemas. Re-sending identical preamble is a common source of burn.

LLM + prompt

Model
  + instructions
  + repository
  + build
  + tools
  + runtime
  + available evidence
  + project knowledge
  + feedback loops

Iteration 2: Give the agent the navigation tools engineers already use

When working through the Iteration 2 Give the stage, write down the contract first: required inputs, success signal, and what happens on partial failure. That checklist keeps later code changes honest. Treat this stage as a contract between inputs and validated outputs. Name the artifacts, define success checks, and refuse silent partial completion. Cache stable system instructions and tool schemas. Re-sending identical preamble is a common source of burn.

shell + filesystem + internet

interface
   ↓
implementation
   ↓
usage
   ↓
test

Iteration 3: Sometimes the best context is a human pointing at the right file

When working through the Iteration 3 Sometimes the stage, write down the contract first: required inputs, success signal, and what happens on partial failure. That checklist keeps later code changes honest. Record timings and token or query cost next to functional results. Cost visibility early prevents surprise bills when the path moves from demo to shared environments. Cache stable system instructions and tool schemas. Re-sending identical preamble is a common source of burn. When working through the Iteration 3 Sometimes the stage, write down the contract first: required inputs, success signal, and what happens on partial failure. That checklist keeps later code changes honest. Document the happy path and the recovery path together. Retries, human gates, and dead-letter handling are part of the product, not later polish.

AllMiniLmL6V2EmbeddingModel
        ↓
AbstractInProcessEmbeddingModel
        ↓
OnnxBertBiEncoder

Hugging Face tokenizer
        ↓
ONNX Runtime
        ↓
token representations
        ↓
pooling
        ↓
normalization
        ↓
embedding

Iteration 4: Why are we deciding what the agent needs to learn?

The Iteration 4 Why are stage works best when treated as a measurable surface. Capture one golden transcript, one failure case, and the rollback note before expanding scope. Prefer small, testable units over sprawling scripts. When a step fails, the failure should point at a single responsibility rather than a tangled pipeline. Budget tokens per turn and per session. Agentic tools expand context aggressively; hard caps keep demos from becoming surprise invoices.

A small experiment with Integrallis Vectors

The A small experiment with stage works best when treated as a measurable surface. Capture one golden transcript, one failure case, and the rollback note before expanding scope. Treat this stage as a contract between inputs and validated outputs. Name the artifacts, define success checks, and refuse silent partial completion. Budget tokens per turn and per session. Agentic tools expand context aggressively; hard caps keep demos from becoming surprise invoices.

../vectors/

Initial working model
        ↓
low confidence recognized
        ↓
specific evidence requested
        ↓
source inspected
        ↓
previous hypothesis falsified
        ↓
new working model
        ↓
better engineering recommendation

Yes, the agent learned…

The Yes the agent learned stage works best when treated as a measurable surface. Capture one golden transcript, one failure case, and the rollback note before expanding scope. Record timings and token or query cost next to functional results. Cost visibility early prevents surprise bills when the path moves from demo to shared environments. Budget tokens per turn and per session. Agentic tools expand context aggressively; hard caps keep demos from becoming surprise invoices. The Yes the agent learned stage works best when treated as a measurable surface. Capture one golden transcript, one failure case, and the rollback note before expanding scope. Document the happy path and the recovery path together. Retries, human gates, and dead-letter handling are part of the product, not later polish.

An agent’s learning should outlive the agent.

For the An agent s learning stage, define the inputs, the owner of the step, and the exit criteria before changing code. Operators should be able to re-run the step from a known checkpoint without guessing hidden state. Prefer small, testable units over sprawling scripts. When a step fails, the failure should point at a single responsibility rather than a tangled pipeline. Prefer structured outputs with schema validation over free-form prose when the next step is code or a tool call.

docs/engineering/

docs/knowledge/

docs/knowledge/vector-backends/
    onnx-embedding-pipeline.md
    integrallis-vectors.md
    candidate-assessment.md

Local embedding baseline:
- all-MiniLM-L6-v2
- 384 dimensions
- ONNX Runtime
- DJL HuggingFaceTokenizer
- mean pooling
- L2 normalization

Long inputs:
- partitioned before inference
- embeddings combined using token-count weightingLangChain4j:
- useful as a verified reference implementation
- not required by the runtime designUpstream source:
- available locally for deeper verification

retained knowledge
       ↓
task understanding
       ↓
remaining uncertainty
       ↓
targeted evidence
       ↓
new learning
       ↓
updated retained knowledge
       ↓
next agent

Research is part of delegation

For the Research is part of stage, define the inputs, the owner of the step, and the exit criteria before changing code. Operators should be able to re-run the step from a known checkpoint without guessing hidden state. Treat this stage as a contract between inputs and validated outputs. Name the artifacts, define success checks, and refuse silent partial completion. Prefer structured outputs with schema validation over free-form prose when the next step is code or a tool call.

"Agent, do everything."

"Human specifies every line."

The agent is not a genie in a lamp

For the The agent is not stage, define the inputs, the owner of the step, and the exit criteria before changing code. Operators should be able to re-run the step from a known checkpoint without guessing hidden state. Record timings and token or query cost next to functional results. Cost visibility early prevents surprise bills when the path moves from demo to shared environments. Prefer structured outputs with schema validation over free-form prose when the next step is code or a tool call. For the The agent is not stage, define the inputs, the owner of the step, and the exit criteria before changing code. Operators should be able to re-run the step from a known checkpoint without guessing hidden state. Document the happy path and the recovery path together. Retries, human gates, and dead-letter handling are part of the product, not later polish.

Coding Agent
                          │
          ┌───────────────┼───────────────┐
          │               │               │
       Harness         Knowledge        Research
          │               │               │
        tools          project facts     source
        build          decisions         docs
        IDE            constraints       experiments
        runtime        prior learning    external evidence
          │               │               │
          └───────────────┼───────────────┘
                          ↓
                    Clear boundaries
                          ↓
                   Precise delegation
                          ↓
                    Implementation
                          ↓
                     Verification
                          ↓
                  Retained knowledge
                          │
                          └──────→ next agent

From prompting to engineering working conditions

When working through the From prompting to engineering stage, write down the contract first: required inputs, success signal, and what happens on partial failure. That checklist keeps later code changes honest. Prefer small, testable units over sprawling scripts. When a step fails, the failure should point at a single responsibility rather than a tangled pipeline. Cache stable system instructions and tool schemas. Re-sending identical preamble is a common source of burn.

better environment
      ↓
cheaper investigation
      ↓
better evidence
      ↓
better decisions
      ↓
retained learning
      ↓
better starting environment
      ↓
next agent

Where OSK came from

When working through the Where OSK came from stage, write down the contract first: required inputs, success signal, and what happens on partial failure. That checklist keeps later code changes honest. Treat this stage as a contract between inputs and validated outputs. Name the artifacts, define success checks, and refuse silent partial completion. Cache stable system instructions and tool schemas. Re-sending identical preamble is a common source of burn.

A different way to program with agents

When working through the A different way to stage, write down the contract first: required inputs, success signal, and what happens on partial failure. That checklist keeps later code changes honest. Record timings and token or query cost next to functional results. Cost visibility early prevents surprise bills when the path moves from demo to shared environments. Cache stable system instructions and tool schemas. Re-sending identical preamble is a common source of burn. When working through the A different way to stage, write down the contract first: required inputs, success signal, and what happens on partial failure. That checklist keeps later code changes honest. Document the happy path and the recovery path together. Retries, human gates, and dead-letter handling are part of the product, not later polish.

Human request
      ↓
Agent generates code

Human hypothesis
      ↓
discussion
      ↓
agent reconnaissance
      ↓
identify uncertainty
      ↓
targeted research
      ↓
retained evidence
      ↓
human + agent design
      ↓
implementation
      ↓
real-world friction
      ↓
verification
      ↓
revised architecture
      ↓
new retained knowledge

These are hypotheses, not laws

The These are hypotheses not stage works best when treated as a measurable surface. Capture one golden transcript, one failure case, and the rollback note before expanding scope. Prefer small, testable units over sprawling scripts. When a step fails, the failure should point at a single responsibility rather than a tangled pipeline. Budget tokens per turn and per session. Agentic tools expand context aggressively; hard caps keep demos from becoming surprise invoices.

Operational checklist

For the Operational checklist stage, define the inputs, the owner of the step, and the exit criteria before changing code. Operators should be able to re-run the step from a known checkpoint without guessing hidden state.

Keep configuration outside application code. Environment files, secret stores, and feature flags belong in one place operators can audit without reading the whole graph.

Prefer structured outputs with schema validation over free-form prose when the next step is code or a tool call.

Checkpoint after expensive steps. Resume should not re-bill the same LLM call when an operator retries a later node.

Pin dependency versions and record the image digest that ran the demo. Reproducibility beats tribal knowledge.

Treat this stage as a contract between inputs and validated outputs. Name the artifacts, define success checks, and refuse silent partial completion.

Before promoting the stack, freeze versions, capture a golden transcript for the critical path, and confirm rollback steps. Shared environments need rate limits, tenancy checks, and a clear owner for secret rotation. Prefer boring reliability over clever one-off demos.

Batch note for ddfa012877c8: keep provider keys out of the repo, set a per-session token ceiling, and store transcripts next to the eval fixtures so later model swaps stay comparable.

For the hardening note 0 stage, define the inputs, the owner of the step, and the exit criteria before changing code. Operators should be able to re-run the step from a known checkpoint without guessing hidden state. Record timings and token or query cost next to functional results. Cost visibility early prevents surprise bills when the path moves from demo to shared environments.

Hardening detail 0/867: measure wall time, error class, and token spend for this note, then decide whether to keep the change based on a fixed question set rather than anecdote.