# How Code Quality Standards Are Enforced in the no-mistakes Project

> Discover how the no-mistakes project enforces code quality standards with a three-layer linting process that includes automated fixes and human review for flawless code.

- Repository: [Kun Chen/no-mistakes](https://github.com/kunchenguid/no-mistakes)
- Tags: best-practices
- Published: 2026-07-11

---

**The no-mistakes project enforces code quality standards through a three-layer Lint step that combines configuration-driven commands, agent-driven housekeeping passes, and automated fix workflows to ensure every run either passes cleanly, auto-fixes safe issues, or blocks for human review.**

The **no-mistakes** tool, developed in the `kunchenguid/no-mistakes` repository, treats code quality as a blocking pipeline concern rather than a cosmetic afterthought. Its enforcement mechanism operates through tightly coupled layers that span configuration management, AI agent interaction, and strict result handling to prevent any lint violation from slipping into the codebase.

## The Three-Layer Enforcement Architecture

The project implements code quality standards through three distinct layers that execute for every pipeline run. Each layer handles a specific aspect of lint enforcement, from configuration overrides to runtime execution.

### Configuration Layer

Per-repository overrides for lint commands are read from the `Commands` section of the merged configuration file ([`.no-mistakes.yaml`](https://github.com/kunchenguid/no-mistakes/blob/main/.no-mistakes.yaml)). According to the source code in [`internal/config/config.go`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/config/config.go) (lines 46-53), the system checks for a user-defined lint command before falling back to default behavior.

If no command is supplied in the configuration, the pipeline automatically triggers an **agent-driven lint pass** rather than failing silently. This fail-closed behavior ensures that code quality standards are always enforced, even without explicit user configuration.

### Agent-Driven Housekeeping

When `Commands.Lint` is empty, the combined document and lint housekeeping pass runs once per pipeline round. As implemented in [`internal/pipeline/steps/lint.go`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/pipeline/steps/lint.go) (lines 22-32), this layer asks the agent to discover appropriate linters and formatters for the project, execute them, and return structured findings.

The results are cached in the shared `HousekeepingLintResult` structure. This cache is later consumed by the `LintStep` to avoid redundant agent invocations, optimizing performance while maintaining strict enforcement.

### LintStep Execution

The core enforcement logic resides in [`internal/pipeline/steps/lint.go`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/pipeline/steps/lint.go) (lines 12-28), where the `LintStep` executes a four-phase process:

1. **Prompt generation** – Constructs a detailed prompt instructing the agent to focus exclusively on lint, format, and static-analysis issues, explicitly forbidding test execution or broader validation.
2. **Agent run** – The agent returns a JSON payload containing `findings` plus a concise commit-style summary.
3. **Result handling** – Non-zero exit codes from external linters create **blocking findings** (`NeedsApproval: true`) and mark the step as `AutoFixable`.
4. **Auto-fix verification** – When auto-fix is enabled, the step invokes the agent in fix mode, applies changes, and re-runs the external linter to verify resolution.

The strict prompting rules (lines 51-55 of [`lint.go`](https://github.com/kunchenguid/no-mistakes/blob/main/lint.go)) explicitly prohibit the agent from reporting issues it already fixed, refactoring beyond the root cause, or running tests, ensuring the step remains focused on code quality concerns only.

## Auto-Fix and Approval Workflows

The enforcement system distinguishes between auto-fixable issues and those requiring human intervention. As defined in [`internal/types/findings.go`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/types/findings.go) (lines 22-40), findings are parsed into the internal `types.Finding` structure where blocking findings (categorized as `error` or `warning`) cause the pipeline to **park** and await human approval.

The auto-fix mechanism operates with configurable limits set via the `AutoFix.Lint` numeric value in [`.no-mistakes.yaml`](https://github.com/kunchenguid/no-mistakes/blob/main/.no-mistakes.yaml). This value determines how many automatic fix attempts are permitted before the step requires manual review. If the limit is exceeded or the fix fails verification, the pipeline blocks rather than allowing potentially degraded code to proceed.

When fixes are applied successfully, the agent must emit a one-sentence summary under ten words (such as `"no-mistakes(lint): fix lint issues"`), which becomes the git commit message. This requirement ensures auditability and readable project history.

## Configuration Examples

### Declaring Lint Commands

Configure project-specific linting via [`.no-mistakes.yaml`](https://github.com/kunchenguid/no-mistakes/blob/main/.no-mistakes.yaml):

```yaml
commands:
  lint: "golangci-lint run ./..."
auto_fix:
  lint: 2          # allow up to two auto-fix attempts

```

The `lint` field maps to `config.Commands.Lint` in [`internal/config/config.go`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/config/config.go), while `auto_fix.lint` controls the retry limit enforced by the pipeline.

### Prompt Construction

The following excerpt from [`internal/pipeline/steps/lint.go`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/pipeline/steps/lint.go) (lines 34-56) illustrates how the system constrains agent behavior to maintain code quality focus:

```go
prompt := fmt.Sprintf(
    `Detect the linting and formatting tools for this project, run the relevant checks yourself, apply safe fixes, and verify the result.

Context:
- branch: %s
- base commit: %s
- target commit: %s

Task:
- Discover the configured linters and formatters for this repository.
- Only lint or format the relevant changed files when possible.
- Apply safe formatter, linter, and static-analysis fixes yourself.
- Re-run the relevant checks after fixing.
- Report only unresolved lint, format, or static-analysis issues as structured findings.
- If everything is clean or fixed, return an empty findings array.

Rules:
- Do not run tests or broader behavioral validation.
- Focus on lint, format, and static-analysis issues only.
- Do not report issues you already fixed.
- The summary must be one concise sentence fragment suitable for a git commit subject.
- Keep the summary under 10 words.%s`,
    sctx.Run.Branch, baseSHA, sctx.Run.HeadSHA, reassessHistory,
)

```

### Auto-Fix Implementation

The fix workflow in [`internal/pipeline/steps/lint.go`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/pipeline/steps/lint.go) (starting at line 104) demonstrates how the pipeline handles remediation:

```go
if sctx.Fixing {
    // ask the agent to fix lint issues first
    summary, err := executeFixMode(sctx, s.Name(), fixExecutionOptions{
        LogMessage: "asking agent to fix lint issues...",
        Prompt:     fixPrompt,
        ErrorPrefix: "agent fix lint",
        FallbackSummary: "fix lint issues",
    })
    // commit the fixes and re-run the external linter
}

```

## Summary

- **Three-layer architecture**: Configuration overrides, agent-driven housekeeping, and `LintStep` execution work together to enforce standards without gaps.
- **Fail-closed defaults**: Missing lint commands trigger agent discovery rather than skipping validation, ensuring continuous enforcement.
- **Structured findings**: The `types.Finding` system categorizes violations and blocks the pipeline on errors while reporting informational issues.
- **Controlled auto-fix**: The `AutoFix.Lint` configuration limits automatic remediation attempts and requires human approval when exceeded.
- **Auditability requirements**: All fixes generate concise commit messages under ten words, maintaining transparent project history.

## Frequently Asked Questions

### What happens if I don't configure a lint command in [`.no-mistakes.yaml`](https://github.com/kunchenguid/no-mistakes/blob/main/.no-mistakes.yaml)?

If no `commands.lint` value is provided, the pipeline executes an agent-driven housekeeping pass that discovers and runs appropriate linters automatically. This cached result is then consumed by the `LintStep`, ensuring code quality standards are enforced even without explicit configuration. The system fails closed rather than allowing unlinted code to pass.

### How does the no-mistakes project prevent auto-fixes from introducing new bugs?

The auto-fix workflow limits the number of attempts via the `AutoFix.Lint` configuration value. After applying fixes, the step re-runs the external lint command to verify the issues are resolved. Additionally, the agent is strictly prompted to apply only "safe" fixes and to avoid refactoring beyond the root cause, minimizing the risk of behavioral changes.

### Can the lint step be bypassed if the agent fails to execute?

No. If the lint command is missing and the shared `HousekeepingLintResult` cannot be parsed from the cache, the step forces a human approval via `documentApprovalOutcome`. This guarantees that technical failures in the agent or external tools cannot be used to circumvent code quality enforcement.

### Where are lint violations stored for review?

Lint findings are parsed into the `types.Finding` structure defined in [`internal/types/findings.go`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/types/findings.go). These findings carry metadata including severity levels and `NeedsApproval` flags. Blocking findings (errors and warnings) park the pipeline and surface in the review interface, while the underlying data structure supports programmatic access for custom reporting integrations.