Full Validation Pipeline

Scenario

You maintain a production TypeScript API where changes pass through several validation layers before deployment.

The project has:

• formatting checks;
• linting;
• TypeScript type checking;
• unit and integration tests;
• a production build.

CI runs the complete validation pipeline.

During development, agents may use targeted checks for faster feedback, but substantial changes should pass the same core checks expected by CI before completion.

Repository Structure

production-api/
├── src/
│   ├── routes/
│   ├── services/
│   ├── repositories/
│   └── shared/
├── tests/
│   ├── unit/
│   └── integration/
├── package.json
├── tsconfig.json
└── AGENTS.md

Relevant scripts:

{
  "scripts": {
    "format:check": "prettier --check .",
    "lint": "eslint .",
    "typecheck": "tsc --noEmit",
    "test": "vitest run",
    "build": "tsc -p tsconfig.build.json",
    "validate": "pnpm format:check && pnpm lint && pnpm typecheck && pnpm test && pnpm build"
  }
}

AGENTS.md

# Project Instructions

## Development Validation

During implementation:

- run targeted tests for the behavior being changed;
- run `pnpm typecheck` after meaningful TypeScript changes;
- run `pnpm lint` when source code changes.

## Full Validation

Run `pnpm validate` before completing:

- substantial feature work;
- cross-cutting changes;
- shared-library changes;
- build or configuration changes.

For very small isolated changes, run the checks relevant to the modified area and state what was validated.

## Failures

- Do not bypass a failing validation step merely to complete the task.
- Fix failures caused by your change.
- If a failure is pre-existing or unrelated, identify it clearly rather than modifying unrelated code without justification.

## CI

- Keep local validation compatible with the repository's CI workflow.
- Do not change CI checks simply to make a failing change pass.

What This Does

This establishes two levels of validation:

Fast development feedback
        ↓
Targeted tests / lint / typecheck

Full completion validation
        ↓
format → lint → typecheck → test → build

The agent can work efficiently while implementing a change without losing sight of the repository's full quality gate.

For substantial work, one command provides the final verification:

pnpm validate

What This Does NOT Do

The file does not require the complete pipeline after every keystroke or tiny edit.

That would make the workflow unnecessarily slow.

It also does not instruct the agent to "fix everything" when validation fails.

Suppose:

pnpm validate

reveals an unrelated failing test that existed before the task.

Automatically changing unrelated production code to make the suite green could be dangerous.

The instructions instead require the agent to distinguish between:

Failure caused by this change

and:

Existing/unrelated failure

Why These Instructions Matter

A production validation pipeline usually contains checks that catch different problems.

For example:

Formatter
   ↓
Formatting consistency

Linter
   ↓
Static project rules

Type checker
   ↓
Type correctness

Tests
   ↓
Expected behavior

Build
   ↓
Production compilation

Passing one stage does not guarantee that later stages will pass.

Consider a change that introduces an invalid production import.

Unit tests might pass because they mock the affected module.

The production build may still fail.

That is why substantial changes should eventually pass the complete pipeline.

Key Decisions

Provide one canonical full-validation command

Instead of requiring an agent to remember:

pnpm format:check
pnpm lint
pnpm typecheck
pnpm test
pnpm build

the repository provides:

pnpm validate

The underlying pipeline remains defined in package.json.

Keep development feedback fast

Targeted validation is useful while coding.

For example:

pnpm test -- tests/unit/orders.test.ts

may provide feedback much faster than the complete suite.

The important distinction is between:

iteration validation and completion validation.

Don't bypass quality gates

If a check fails because of the new change, the normal response is to fix the change.

Removing a test, disabling a lint rule, or weakening CI is not an appropriate shortcut unless the task specifically requires changing that policy.

Report unrelated failures

An agent may encounter an unhealthy repository.

Useful behavior is:

1. determine whether the failure is related;
2. fix it if the change caused it;
3. otherwise report it clearly;
4. avoid expanding task scope without reason.

Keep local and CI expectations aligned

If CI runs a validation pipeline that developers cannot reasonably reproduce locally, debugging becomes harder.

A repository-level command such as:

pnpm validate

creates a useful shared interface for humans, agents, and CI.

When to Use This Pattern

Use this pattern when:

• the project has several validation stages;
• CI enforces a quality pipeline;
• full validation can be expensive;
• targeted checks are useful during development;
• agents need guidance about handling existing failures.

This pattern is particularly useful for production applications where "the code looks correct" is not an adequate definition of completion.