How to Build a DeepSeek Coding Harness

Building a DeepSeek coding harness is less about creating a clever prompt and more about designing a reliable execution system. The model needs a disciplined way to inspect a repository, choose an action, run a tool, observe the result, and decide what to do next.

This guide focuses on that system boundary. It assumes you can already send a request to a DeepSeek-compatible endpoint and receive a model response.

Start with an explicit agent loop

Keep the orchestration loop small enough to understand. In simplified form:

while (!task.done) {
  const context = await buildContext(task, session);
  const response = await model.respond(context, tools);
  const result = await execute(response.toolCall, policy);
  await session.append({ response, result });
  task = evaluate(task, response, result);
}

Production code needs cancellation, retries, malformed-call handling, token limits, and approval states, but the core relationship should remain visible: model decision → controlled execution → observed result.

If tool execution is hidden behind many unrelated abstractions, diagnosing a failed agent becomes difficult.

Define narrow tool contracts

Begin with the smallest useful set:

• search for paths and symbols.
• read for bounded file ranges.
• patch for reviewable edits.
• shell for project commands.
• status for Git state and diffs.

Each tool should validate its input and return structured output. Limit file sizes, command duration, result length, and writable paths. Treat model-generated arguments as untrusted input even when the task itself is trusted.

Do not make every operation a shell command. A dedicated read or patch tool is easier to validate, log, and explain than a free-form command that can do anything.

Build context progressively

The context builder is one of the most important parts of a DeepSeek harness. Its job is not to load everything. Its job is to supply the minimum state required for the next correct decision.

A practical order is:

1. User task and current plan.
2. Repository instructions such as AGENTS.md.
3. Relevant file excerpts discovered through search.
4. Current diff and recent tool results.
5. A compact usage summary.

Separate durable facts from transient output. A project rule may matter for the entire session; a 500-line compiler trace usually needs to be summarized after the immediate error is resolved.

Context compaction should preserve decisions, open questions, changed files, and verification state. It should not merely truncate the oldest messages.

Put permissions in policy code

Prompt instructions are not a security boundary. The execution policy should decide:

• Which repository roots are readable and writable.
• Whether commands can access the network.
• Which environment variables are available.
• Which commands require human approval.
• How destructive targets are resolved and validated.

Run ordinary development commands in an OS sandbox when possible. Keep permission escalation explicit, scoped, and visible in the session trace.

Also distinguish authorization by request type. A request to diagnose a failure allows inspection; it does not automatically authorize changing production state.

Treat tests as a first-class tool result

The harness should make it easy for the model to run a narrow check, read the failure, and continue. Test results need stable formatting and bounded output so one noisy command does not consume the whole context window.

Capture at least:

• Command and working directory.
• Exit code and duration.
• Relevant stdout and stderr.
• Whether output was truncated.
• The files changed since the previous check.

Encourage a narrow-to-broad verification strategy. A focused unit test gives faster feedback than repeatedly running the entire build.

Persist a replayable session

Store messages, reasoning metadata where available, tool calls, tool results, approvals, patches, and usage. An append-only JSONL session is simple, inspectable, and resilient to partial writes.

Give each entry a stable ID and timestamp. Record enough information to reconstruct why a tool ran, but never persist secrets returned by the environment.

A replayable session supports resume, debugging, audit, and eventually deterministic harness tests with a stubbed model.

Add parallel agents only after isolation

Parallel agents are useful for independent exploration, implementation, review, and tests. They also create new failure modes: conflicting edits, duplicated context, and unclear ownership.

Before adding concurrency, define:

• A maximum number of active agents.
• Which tasks are read-only.
• When an implementation gets an isolated Git worktree.
• How findings return to the parent agent.
• Who owns the final integration and verification.

Parallelism should reduce critical-path time, not make the session harder to understand.

Measure context, cache, tokens, and cost

Capture usage on every model turn and aggregate it at the session level. Show input tokens, output tokens, cached tokens when available, reasoning, context capacity, and estimated spend.

Then connect those metrics to behavior. Repeatedly loading the same large file suggests a context-management problem. A sub-agent that consumes many tokens but returns no new evidence suggests a delegation problem.

The harness should make inefficiency debuggable.

Define completion as evidence

An agent should not stop only because the model says it is done. Completion criteria should come from the task and repository:

• Requested behavior is implemented.
• Relevant tests pass.
• Production build or type check passes when required.
• Diff contains no unrelated changes.
• Remaining limitations are reported clearly.

The final response is a compact handoff: outcome, changed files, verification, and anything the developer still needs to decide.

Build or adopt?

Building your own harness makes sense when you need unusual tools, policy, or deployment constraints. It also means owning session storage, tool safety, model replay, context management, testing, and the user interface.

DSCode is an open-source DeepSeek coding harness that already implements the core repository loop. You can use it directly or study its approach before designing your own.

For the conceptual foundation, read What Is a DeepSeek Harness?. For the user-facing workflow, read DeepSeek Code Agent: From Prompt to Tested Repository Change.