harness-engineeringbackendcontexttutorialopencodenestJSai-agents

Harness Agent for Backend: The First Pillar — Context from AGENTS.md with OpenCode

Leer en español

This article is the direct continuation of Building a Harness Agent for Backend: Step-by-Step Guide with Pi. In that first part we installed the agent, configured tools, skills, and automation. Now we put it into practice — real project, real context, real code.

In the first installment we talked about the four pillars of harness engineering: Constrain, Inform, Verify, Correct. But we stayed on the surface — theory, generic examples, best practices.

This article is different. Here we build. We’re going to:

  1. Create a real backend project with NestJS 11 and pnpm
  2. Use OpenCode to craft a custom AGENTS.md with harness workflow
  3. Install the harness skills — grill-me, nestjs-best-practices, qa
  4. Enrich that AGENTS.md with context — the first pillar of the harness

Everything you do here, your agent will do on its own later.

Why Context is the First Pillar

The four pillars of harness engineering have a order for a reason:

OrderPillarQuestion it answers
1Context (Inform)What does the agent need to know to work?
2ConstraintsWhat can’t the agent do?
3VerificationHow do we know it did it right?
4CorrectionWhat happens when it makes a mistake?

Without context, the other pillars have no foundation. Context is the bedrock of the harness.

If your agent doesn’t know:

  • What stack you use (Express vs FastAPI vs NestJS)
  • What folder structure your project has
  • What coding rules you follow
  • What commands it needs to run, test, and build

…then it doesn’t matter how good your skills are or how robust your tests are. The agent will be operating blind.

The golden rule of harness engineering: From the agent’s perspective, anything it can’t access in context doesn’t exist. The repository must be the single source of truth.

Creating the NestJS Project

NestJS 11 is a progressive Node.js framework for building efficient, reliable, and scalable backend applications. It uses TypeScript by default, has a modular architecture, and supports dependency injection — ideal for a harness agent. We’ll use pnpm as our package manager for its speed and strict dependency resolution.

Prerequisites

Make sure you have Node.js 18+ and the NestJS CLI installed:

node --version   # ≥ 18
pnpm --version   # ≥ 9

# Install NestJS CLI globally
pnpm add -g @nestjs/cli

Create the project

# Create a new NestJS project with pnpm
npx @nestjs/cli new --package-manager pnpm harness-nestjs

Once created, the base structure looks like this:

harness-nestjs/
├── src/
│   ├── app.controller.spec.ts
│   ├── app.controller.ts
│   ├── app.module.ts
│   ├── app.service.ts
│   └── main.ts
├── test/
│   ├── app.e2e-spec.ts
│   └── jest-e2e.json
├── nest-cli.json
├── package.json
├── pnpm-lock.yaml
├── tsconfig.json
├── tsconfig.build.json
├── eslint.config.mjs
└── .gitignore

Verify it works:

cd harness-nestjs
pnpm run start:dev

You should see:

[Nest] 12345  - 06/02/2026, 12:00:00 PM     LOG [NestApplication] Nest application successfully started

Now we have a real backend project. But our agent knows nothing about it — not the structure, not the rules, not even that it exists. It’s time to build the context.

Generating AGENTS.md with OpenCode

OpenCode is an AI agent that runs in your terminal, and its /init command is a quick way to generate a baseline AGENTS.md. But here’s the thing — the baseline is just a skeleton. It gives you stack detection, a file tree, and some commands, but it doesn’t know how your agent should work.

That’s where the harness philosophy comes in. Instead of leaving the AGENTS.md generic, we’re going to craft it intentionally. We’ll use OpenCode as the tool, but we decide what goes in.

Step 1: Launch OpenCode

Make sure OpenCode is installed:

opencode --version

If you don’t have it: pnpm add -g opencode or visit opencode.ai.

Now navigate to the project root and launch OpenCode:

cd harness-nestjs
opencode

Step 2: Run /init as a starting point

Inside OpenCode, type:

/init

OpenCode scans the project and generates a basic AGENTS.md with the stack, file tree, and npm commands. It’s a decent starting point — but it’s not the final product. The commands will say npm (because NestJS CLI defaults to npm) even though we use pnpm. The workflow will be absent. The skills won’t be referenced.

So we take that file and we make it our own.

What we actually put in AGENTS.md

Instead of keeping the generic output, we write an AGENTS.md that answers the real questions an agent needs to work effectively in this harness:

# Harness NestJS Template

Backend with NestJS, strict typing, Swagger documentation, and production practices enforced by the `nestjs-best-practices` skill.

## Workflow

1. **Grill the design** — Use `grill-me` skill to stress-test requirements
2. **Review context** — Check project patterns, dependencies, Docker setup
3. **Implement** — Use `nestjs-best-practices` skill during code generation
4. **Persist** — Save functional requirements via engram MCP
5. **Test** — QA phases: requirements validation, security audit, scenario execution

## Commands

```sh
pnpm run build         # nest build -> dist/
pnpm run start:dev     # watch mode
pnpm run test          # jest (unit: src/**/*.spec.ts)
pnpm run test:e2e      # jest (e2e: test/**/*.e2e-spec.ts)
pnpm run test:cov      # jest --coverage
pnpm run lint          # eslint --fix
pnpm run format        # prettier --write

Conventions

  • Package manager: pnpm (lockfile v9). Do NOT use npm or yarn.
  • Testing: Jest + ts-jest. E2e uses supertest.
  • Lint: ESLint v9 flat config, type-aware via projectService: true.
  • Format: Prettier — single quotes, trailing commas.
  • Port: process.env.PORT or 3000.

Notice what's different from the `/init` output:

1. **We fixed the commands** — `/init` detects what's in `package.json` as-is, but it doesn't know your conventions. We changed `npm` to `pnpm` and added explicit test patterns.
2. **We added a workflow** — The agent now knows the **order of operations**: grill → review → implement → persist → test. This is the harness.
3. **We referenced skills by name** — `grill-me`, `nestjs-best-practices` — the agent knows what tools to use and when.
4. **We documented conventions** — ESLint version, Prettier config, port conventions. The agent doesn't have to guess.

This is the **base context**. But we can go deeper.

---

## Enriching AGENTS.md: Context as the Single Source of Truth

The `AGENTS.md` is the first thing your agent reads. It defines **everything it knows about your code and your workflow**.

Most tutorials stop at documenting the tech stack: "you use Prisma, PostgreSQL, JWT." That's table stakes. The real power is in documenting **how the agent should work** — the process, the order of operations, the tools it needs to reach for at each step.

That's what we're going to do here. Instead of filling `AGENTS.md` with hypothetical dependencies (Prisma, Redis, Docker — which we don't have yet), we enrich it with:

1. **Dimensionality** — What kind of project is this? How big is it?
2. **Workflow** — What are the step-by-step phases the agent follows?
3. **Skills** — Which skills fire at each phase and why
4. **Conventions** — The real rules of this project

### 1. Dimensionality

First, describe the project's scope so the agent understands the playing field:

```markdown
## Dimensionality

Application with workers, queues, and Redis caching. Clean API contracts
for both payload and response. Swagger documentation. High test coverage.

This tells the agent: we care about infrastructure patterns (workers, queues, cache), API quality (contracts, Swagger), and reliability (coverage). The agent now knows what GOOD looks like in this project.

2. Workflow Definition

This is the heart of harness enrichment. We define an exact step-by-step process:

## Paso a paso de implementación

1. **Grill the requirement** — Use the `grill-me` skill to determine
   or deepen the requirement before writing any code
2. **Review context** — Check current project patterns, dependencies,
   and execution tools (Docker, etc.)
3. **Implement** — Use the `nestjs-best-practices` skill during
   code generation
4. **Persist** — Use engram MCP to save functional requirements,
   not implementation details
5. **Test** — QA session with two phases:
   - Phase 1: Determine requirements the implementation must satisfy
   - Phase 2: Find gaps (security, SQL injection, web vulnerabilities)
   - Phase 3: Execute QA scenarios via `qa-nestjs`
   - Phase 4: Feedback loop — repeat 3+ if issues found

Every line serves a purpose:

  • Grill-me prevents the agent from coding the wrong thing. It forces a design conversation before implementation.
  • nestjs-best-practices ensures every line of generated code follows production patterns — dependency injection, error handling, security, performance.
  • Engram MCP persists what was learned. The agent saves what it built and why, not the raw code.
  • QA + qa-nestjs creates a structured verification loop. The agent audits its own work for functional gaps and security issues.

3. Command Reference

Fix the commands to match reality. The /init output had npm — we use pnpm:

## Commands

pnpm run build         # nest build -> dist/
pnpm run start:dev     # watch mode
pnpm run test          # jest (unit: src/**/*.spec.ts)
pnpm run test:e2e      # jest (e2e: test/**/*.e2e-spec.ts)
pnpm run test:cov      # jest --coverage
pnpm run lint          # eslint --fix
pnpm run format        # prettier --write

- No `tsc --noEmit` — `pnpm run build` is the typecheck command
- Codegen: `nest g module <name>`, `nest g controller <name>`, etc.

4. Conventions

Document the non-negotiables:

## Conventions

- **Package manager**: pnpm (lockfile v9). Do NOT use npm or yarn.
- **Testing**: Jest + ts-jest. E2e uses supertest.
- **Lint**: ESLint v9 flat config, type-aware via projectService: true.
- **Format**: Prettier — single quotes, trailing commas.
- **Port**: `process.env.PORT` or `3000`.
- **Build**: deleteOutDir: true — cleans dist/ before each build.

5. Architecture

Keep it simple at this stage — the project is a single module:

## Architecture

main.ts -> AppModule -> AppController -> AppService (GET /)

Single module, no database, no auth.
Module organization: src/<domain>/ when adding features.

Installing the Harness Skills

The enrichment above references four skills. Here’s how to install them:

grill-me

Stress-tests requirements before implementation. Forces a design conversation:

npx skills@latest add mattpocock/skills

This installs grill-me (and potentially other skills) under .claude/skills/. When the agent enters the project, it can activate this skill to grill the user about any new feature before writing code.

nestjs-best-practices

40+ rules across 10 categories — architecture, dependency injection, error handling, security, performance, testing, database, API design, microservices, DevOps:

npx skills@latest add kadajett/agent-nestjs-skills --skill nestjs-best-practices

The agent loads this skill during implementation and references the rules automatically. No more manual “remember to validate inputs” — the skill enforces it.

qa & qa-nestjs

QA skills define how the agent validates its own work. Create .agents/skills/qa/SKILL.md and .agents/skills/qa-nestjs/SKILL.md:

  • qa: Interactive QA session — the user reports bugs conversationally, the agent explores the codebase for context, and files GitHub issues
  • qa-nestjs: Executes QA scenarios specifically for NestJS implementations, checking functional requirements, security gaps, and execution correctness

These skills close the verification loop. The agent builds → the agent tests → the agent reports → the agent fixes.

The Final AGENTS.md

After enrichment, your AGENTS.md is not a generic scan output — it’s a harness instruction manual. It tells the agent:

  1. What this project is — Dimensionality, scope, quality bar
  2. How to work here — The exact 5-step workflow with skill references
  3. What commands to use — pnpm, not npm. Specific test and build patterns
  4. What rules to follow — ESLint config, Prettier settings, port conventions
  5. What skills to load and when — grill-me, nestjs-best-practices, qa, qa-nestjs

When your agent enters this project, it will:

  1. Read AGENTS.md — understands the project scope and quality expectations
  2. Load the workflow — knows the order: grill → context → implement → persist → test
  3. Activate skills at the right moment — uses nestjs-best-practices during coding, qa after
  4. Run the correct commands — pnpm, not npm. Knows the difference between unit and e2e
  5. Persist learnings — saves functional requirements to engram for future sessions

The Harness in Action: A Real Flow

Let me show you what this looks like in practice. When a developer asks the agent to “add a new module for user management,” here’s what happens:

  1. Grill phase: The agent activates grill-me and interviews the developer. “What fields does a user have? Are there roles? What auth strategy? Do we need pagination? Soft deletes?” By the end, requirements are crystal clear.

  2. Context review: The agent checks AGENTS.md — convention says kebab-case files, PascalCase classes. It checks the architecture — single module, add under src/<domain>/. It checks commands — no Prisma here yet, so it asks or infers.

  3. Implementation: The agent loads nestjs-best-practices. It generates UsersModule, UsersController, UsersService. The skill enforces constructor injection, exception filters, proper DTOs. The code is production-ready from line 1.

  4. Persistence: The agent calls engram MCP to save: “Created UsersModule with CRUD endpoints. Requirements: name, email, role fields. Authorization via JWT guard.”

  5. QA: The agent runs qa-nestjs. It checks: Are there security gaps? SQL injection vectors? Validation missing on any endpoint? Does the response format match conventions? If issues are found, the agent loops back to step 3.

This is the harness in action. The developer doesn’t micromanage — the agent follows the documented workflow automatically.

Workflow: Grilling Your Design

Context isn’t just about static documentation — it’s also about validating your decisions. Before implementing a new module or changing the architecture, use the Grill Me skill to stress-test your design.

This skill interviews you relentlessly about every aspect of your plan, walking down each branch of the decision tree until you reach a shared understanding. It’s the perfect complement to the AGENTS.md — the document provides the context, and Grill Me ensures the design is solid before you write a single line of code.

Install it with:

npx skills@latest add mattpocock/skills

By combining a well-structured AGENTS.md with active design validation, you’re not just informing your agent — you’re building a workflow that prevents costly mistakes early.

What We Accomplished

BeforeAfter
Agent enters the project and knows nothingAgent knows scope, workflow, and conventions
You have to explain the process each timeAgent follows the documented workflow
Skills are optional, used randomlySkills are activated at the right phase
Context is just a tech stack listContext is an instruction manual for the agent
Every session starts from zeroEvery session retakes existing context + engram history

In the Next Article…

The first pillar is in place. The agent has context and skills. In the next article we’ll cover:

  • Pillar 2: Constraints — Rules that tell the agent what NOT to do
  • How to write dependency rules that prevent architecture violations
  • Structural tests that enforce conventions automatically
  • Preventing the agent from generating code outside the defined scope
  • Using the qa skill to catch violations before they reach production

The harness is built layer by layer. Context is the foundation. Give your agent the right instructions, and it builds itself.

Do you have a NestJS project started? The process is the same — create the project, craft the AGENTS.md, install the skills. The stack doesn’t matter as much as the workflow. Try it and let me know how it goes.

Share
D
Diego Duran
@fxckcode

Backend engineer who ships agentic CLI tooling. NestJS, Go, Django, AWS.

GitHub LinkedIn

Related Posts

From DESIGN.md to Pages: How to Generate Production UI with AI Agents Harness Engineering: Building Systems That Make AI Agents Actually Work