Lint Before Completion

Scenario

You have a React application with ESLint configured to enforce important project rules.

The linter checks more than formatting. It catches issues such as:

• invalid imports;
• React hook problems;
• unused variables;
• restricted dependencies;
• project-specific static rules.

Developers expect linting to pass before code changes are considered complete.

You want the coding agent to treat linting as part of the completion workflow rather than an optional cleanup step.

Repository Structure

dashboard/
├── src/
│   ├── components/
│   ├── features/
│   ├── hooks/
│   └── pages/
├── tests/
├── eslint.config.js
├── package.json
└── AGENTS.md

AGENTS.md

# Project Instructions

## Development

- Use `pnpm`.
- Follow the existing source organization under `src`.

## Linting

- Run `pnpm lint` after modifying source code.
- Fix lint errors introduced by your change before completing the task.
- Do not disable lint rules merely to make a new warning or error disappear.
- If an existing lint suppression is relevant to the change, understand why it exists before modifying it.

## Completion

For source-code changes:

- run `pnpm lint`;
- run tests relevant to the changed behavior.

What This Does

This makes linting part of the coding agent's normal workflow.

More importantly, it explains how lint failures should be handled.

The agent should not respond to a lint error by immediately adding something like:

// eslint-disable-next-line

Instead, it should first determine why the configured rule is failing.

The distinction matters because a lint rule may represent a repository-level architectural or correctness constraint.

What This Does NOT Do

This does not mean every lint warning in the entire repository must always be fixed during an unrelated task.

For example, imagine the repository already contains warnings in an untouched legacy module.

An instruction such as:

- Fix every lint issue in the repository before completing any task.

could dramatically expand the scope of a small change.

The better expectation is:

- Fix lint errors introduced by your change before completing the task.

The file also does not encourage agents to modify lint configuration simply because a rule is inconvenient.

Why These Instructions Matter

Suppose an agent adds:

import { useEffect } from "react";

export function Profile() {
  useEffect(() => {
    loadProfile();
  }, []);

  return <ProfileView />;
}

The project's lint configuration may identify a dependency problem.

A poor response would be to silence the rule:

// eslint-disable-next-line react-hooks/exhaustive-deps

without understanding the behavior.

The instruction:

- Do not disable lint rules merely to make a new warning or error disappear.

pushes the agent to investigate the underlying issue first.

The same principle applies to restricted imports.

If ESLint prevents:

import something from "../../other-feature/internal";

the rule may be enforcing an architectural boundary rather than a stylistic preference.

Key Decisions

Treat linting as validation

Linting should happen before completion, not only when someone later notices a CI failure.

Don't silence failures automatically

A suppression can be appropriate, but it should be deliberate.

The important instruction is not:

- Never disable ESLint rules.

That would be unnecessarily absolute.

Instead:

- Do not disable lint rules merely to make a new warning or error disappear.

leaves room for justified exceptions.

Keep task scope controlled

Existing unrelated lint debt should not automatically become part of every task.

The agent should primarily ensure that its own change does not worsen the repository.

Let the linter own mechanical rules

If ESLint already enforces an import restriction, AGENTS.md does not need to reproduce every technical detail of the rule.

It can instead communicate the expected workflow around lint failures.

When to Use This Pattern

Use this pattern when:

• linting is part of CI;
• lint rules encode important project constraints;
• agents should validate source changes before completion;
• automatic lint suppressions could hide real problems;
• the repository may contain existing lint debt that should not expand task scope.

This turns linting from a vague recommendation into a concrete completion requirement.