Constraint-Driven Development

Overview

Other skills describe what good looks like: code-review-and-quality gives five axes, test-driven-development a cycle, security-and-hardening a threat list. That is prose an agent may or may not follow, and none of it survives the session. This skill produces a written record of this project's bar, with numbers and the command that checks each one, that outlives the conversation and runs mechanically.

The reason: when you wrote the code, reading it told you whether it was good. An agent writes more in an afternoon than you will read that week, so judgement moves out of your head and into checks that run around the loop. Those checks need to exist, carry numbers you chose, and fire close enough to the work that the agent fixes its own output.

Spec-driven development says what to build. Test-driven development proves it works. Constraint-driven development defines "good enough to ship" before anyone argues about it in a pull request.

When to Use

• Starting a project or significant feature and no quality bar is written down
• The user asks to "set up constraints", "add quality gates", "define our standards"
• An agent is producing volume nobody reads line by line
• CI runs lint, detekt, and tests, but nobody can say which ones block a merge
• Coverage, startup time, APK size, or accessibility get argued per PR instead of decided once
• Before /build auto or any autonomous loop, where the only thing between the agent and main is a test suite the agent also wrote

Skip when:

• CONSTRAINTS.md already exists and the user isn't changing it — read and follow it
• Spikes, throwaway prototypes, one-off scripts
• The user wants a review now (code-review-and-quality) or a pipeline built (ci-cd-and-automation)

Non-interactive contexts (CI, scheduled loops, autonomous runs): the interview needs a live user. If constraints are missing, apply the Floor below, say you did, and flag the rest for a human.

Core Process

Step 1: Detect Before You Ask

Never ask what you can read. Gather this first:

Report what you found in two lines, then ask only what's left.

Step 2: Four Questions, Each With a Default

Follow the one-question-at-a-time discipline from interview-me, with one change: every question has a default, so "I don't know" still produces a working config.

Q1: Beyond the floor, which do you want enforced?
    (a) Coverage on changed code   (b) Static analysis at zero new issues
    (c) Security: secrets + dependencies   (d) Performance budgets
    (e) Accessibility   (f) Module boundaries
GUESS: (a), (b), (c) — you have Kover and detekt already.
DEFAULT if unsure: (a), (b), (c).
Cost: (d) and (e) need a device or emulator; (f) needs rules written.

Q2: When a check fails mid-task, block or warn?
GUESS: Block. Unattended agents ignore warnings.
DEFAULT if unsure: Block on the floor, warn on the rest for two weeks.

Q3: Target numbers in mind, or measure today and hold the line?
GUESS: Measure. An invented number gets ignored.
DEFAULT if unsure: Measure and hold (see Step 7).

Q4: Slowest check you'll tolerate before the agent hands work back?
GUESS: About 90 seconds — a single module's unit tests plus koverVerify.
DEFAULT if unsure: 90 seconds at task end, unlimited in CI.

Stop at four. A twelve-question intake produces a config nobody understands.

Step 3: Write CONSTRAINTS.md

One file at the repo root. Any agent on any harness can read it, and a change to it shows up in review.

# Constraints

Last reviewed: 2026-10-04 by @owner

## Floor (always enforced, no setup required)

- Builds: `./gradlew assembleDebug` succeeds
- Unit tests: `./gradlew testDebugUnitTest` passes
- No new suppressions without a `// reason:` on the same line: `@Suppress`, `@SuppressLint`, `//noinspection`, `ktlint-disable`, `tools:ignore`
- No new `@Ignore` / `@Disabled` tests, no deleted tests, no assertions stripped from tests that stayed
- No `TODO()`, `NotImplementedError`, or empty `catch {}` on shipped (non-test) paths
- No growth of `lint-baseline.xml` or the detekt baseline
- No secrets in source
- This file does not get weakened to make a change pass

## Enforced with numbers

| Dimension | Rule | Checked by | Runs at |
|-----------|------|-----------|---------|
| Formatting | Zero violations | `./gradlew spotlessCheck` | every edit |
| Static analysis | Zero new detekt issues, maxIssues 0 | `./gradlew :<module>:detekt` | every edit |
| Lint | Zero errors, warnings as errors | `./gradlew lintDebug` | CI |
| Coverage | Changed domain/data modules ≥ 80% lines | `./gradlew :<module>:koverVerify` | task end, CI |
| Secrets | No findings | `gitleaks detect --redact --no-banner` | task end, CI |
| Dependencies | Nothing at high or above | `osv-scanner scan source -r .` | CI |
| Startup | Cold start median ≤ 500ms | `./gradlew :benchmark:connectedBenchmarkAndroidTest` | CI (emulator) |
| APK size | Release APK grows ≤ 100 KB per PR | `diffuse diff` on base vs head APK | CI |

Every row names the command that produces the verdict. A number with no
command is an aspiration, not a constraint.

## Measured, not yet enforced

| Metric | Today | Direction |
|--------|-------|-----------|
| Project line coverage | 62.4% | must not fall |
| lint-baseline.xml issues | 214 | must not grow |
| Release APK size | 18.3 MB | must not grow |

## Exceptions

| ID | Rule | Path | Reason | Owner | Expires |
|----|------|------|--------|-------|---------|
| W1 | detekt LongMethod | `feature/legacy/**` | Rewrite tracked in ENG-441 | @owner | 2027-01-01 |

Then add one line to AGENTS.md and CLAUDE.md: Read CONSTRAINTS.md before writing code. Do not weaken it to make a change pass. (see context-engineering).

Step 4: Install a Tool per Dimension

Picking a dimension means installing something. Don't leave a number with no mechanism, and don't hand-roll a checker when a de facto tool exists — the team's existing config and CI already target these.

Coverage rules live in the module's build file, so the number and the check are the same artifact:

// core/domain/build.gradle.kts
plugins {
    id("org.jetbrains.kotlinx.kover")
}

kover {
    reports {
        verify {
            rule("Domain line coverage — see CONSTRAINTS.md") {
                bound {
                    minValue = 80
                    coverageUnits = kotlinx.kover.gradle.plugin.dsl.CoverageUnit.LINE
                }
            }
        }
    }
}

Five things that bite if skipped:

1. --redact on gitleaks is not optional. Without it the matched secret lands in the agent's transcript, then a log or a commit message. Report the rule and location, never the value.
2. Macrobenchmark, instrumented accessibility checks, and connected* tasks need a device. If CI has no emulator (see ci-cd-and-automation), keep those dimensions measured-only or CI-only on a device farm — don't pretend a JVM test covers them.
3. Scope expensive ones to the change. Pitest on the whole repo takes hours and gets switched off; on the touched module with targetClasses narrowed it takes minutes.
4. Coverage needs no second test run. koverVerify reads the same execution data test produced; wire it after the test task, don't run the suite twice.
5. Baselines are debt ledgers, not escape hatches. lint-baseline.xml and the detekt baseline may shrink. Regenerating one to absorb new issues is a lowered bar (Step 6).

Expose the stages as Gradle tasks so they are reproducible without an agent. A root-level aggregate keeps the commands in one place:

// build.gradle.kts (root)
tasks.register("checkFast") {
    group = "verification"
    description = "Edit loop: formatting + detekt. Mirrors CONSTRAINTS.md."
    dependsOn("spotlessCheck", "detekt")
}

tasks.register("checkTask") {
    group = "verification"
    description = "Task end: checkFast + unit tests + coverage bounds."
    dependsOn("checkFast", "testDebugUnitTest", "koverVerify")
}

tasks.register("checkFull") {
    group = "verification"
    description = "CI: checkTask + full lint + dependency scan."
    dependsOn("checkTask", "lintDebug", "dependencyCheckAnalyze")
}

CONSTRAINTS.md is the canonical source: it carries the reason beside each command and shows up in review. The Gradle tasks mirror it; if they drift, the file wins. Run module-scoped variants in the loop (./gradlew :feature:tasks:detekt) — checkFast at the root is for humans and hooks.

Step 5: Place Checks by Cost

A check that stalls the agent gets switched off, and a switched-off gate is worse than none because the bar still looks like it exists.

Two rules:

1. Scope to the diff. Gate coverage of the module a change touched, not the project — that's a number the agent can move.
2. Cost decides placement. Anything needing a device or a full assembleRelease leaves the edit loop.

Step 6: Guard the Bar Itself

If the agent writes the code and the checks, the checks prove less. Agents don't craft clever loopholes; they hit red and take the cheapest road to green. Watch the diff for these moves:

1. The threshold moved. minValue lowered in a kover { } block, maxIssues raised in detekt.yml, abortOnError = false, a lint.xml severity downgraded to warning/ignore, a rule set active: false, ignoreFailures = true, a row edited in CONSTRAINTS.md.
2. A test got easier. @Ignore/@Disabled added, a test file deleted, assertThat/verify/awaitItem removed from a test that stayed, excludeTestsMatching added to the test task.
3. A checker got silenced. New @Suppress, @SuppressLint, //noinspection, ktlint-disable, tools:ignore without a reason. A grown lint-baseline.xml or detekt baseline is the same move in bulk.
4. Work is unfinished. TODO(), throw NotImplementedError(), an empty catch (e: Exception) {} turning a failure into silence, runCatching { } whose result is discarded.
5. An exception appeared. A new row in the Exceptions table nobody discussed.

None of this needs tooling beyond git diff. Tightening the bar should be silent; loosening it should be loud.

The floor has no de facto tool of its own, so an agent asked to enforce it writes a checker from scratch and two agents write two different ones. A reference implementation ships with this skill in references/floor-guard.md — a Kotlin script, diff-scoped, exit 0/1/2. Adapt it rather than reinventing it.

Not all checks are equally circular. Ask: can the agent make this pass by writing code that doesn't work?

• External — Accessibility Test Framework encodes platform a11y rules, osv-scanner reads a vulnerability database, Macrobenchmark measures a real device. The agent can't argue with these.
• Project — your detekt config, your Konsist rules. A human owns the file.
• Suite — your own tests. Most useful, and the only genuinely circular one.

A bar made entirely of the third kind is worth less. Ensure at least one external constraint is present.

Step 7: Ratchets, When There's No Number

Set 80% coverage on a codebase at 62% and you get a red build forever, then a team that ignores red builds.

Instead: record today's value in "Measured, not yet enforced" with a direction, and refuse to get worse. Every check compares against the recorded value, not an aspiration. When a number improves, update it; when it drops, that's the finding. Lint and detekt baselines are ratchets already — their entry count may only fall.

Models are rewarded for passing tests, which evaluate in seconds. Architectural rot shows up over months and never reaches the weights. A ratchet is the missing penalty, written where the build can see it.

Sane Defaults

When the user has no opinion, use these. Most codebases meet them on day one.

State the number and the reason together. A threshold without a rationale gets deleted by the next person who hits it.

Escalation Path

Three levels of teeth. Start at the first.

1. Written only. CONSTRAINTS.md exists and agents read it. Catches honest mistakes.
2. Scripted. checkFast / checkTask / checkFull Gradle tasks wired into the agent's post-edit hook and CI. Deterministic, no new dependency.
3. Tool-backed. A dedicated runner handling diff scoping, budgets, ratchets, and the guard. Use when the config outgrows a few Gradle tasks; references/floor-guard.md is the starting point for the guard half.

Most projects stop at 2. A first run can be floor-only: the floor guard is diff-only and needs no plugins, so protect the first commit today and add dimensions as each tool lands. Machine-wide tools (gitleaks, osv-scanner) can run CI-only; declare it in Runs at.

Common Rationalizations

Red Flags

• The interview ran past four questions, or produced a config the user can't explain
• A budget the codebase fails today, with no ratchet or plan
• A dimension in CONSTRAINTS.md with a number but no Gradle task or command behind it
• A hand-rolled checker where Lint, detekt, or Kover already exists
• Every constraint judged by the project's own unit tests, no external opinion
• CONSTRAINTS.md, detekt.yml, a kover { } block, or a baseline file changed in the same commit as the feature that was failing
• An exception with no owner, or an expiry more than a year out
• The agent proposed relaxing a threshold instead of fixing the code
• connectedAndroidTest or Macrobenchmark in the edit loop, and someone started passing --no-verify
• Nobody has opened CONSTRAINTS.md since it was written

Verification

• CONSTRAINTS.md exists at the repo root, every number has a stated reason
• The floor passes on the current branch: ./gradlew assembleDebug testDebugUnitTest green and the floor guard exits 0
• Every picked dimension has a tool applied and a command that runs today — paste the output
• Each rule states where it runs; the edit-loop stage finishes in seconds on one module
• Device-dependent dimensions are marked CI-only or measured-only if no emulator is available
• At least one constraint is external (ATF, osv-scanner, Macrobenchmark, gitleaks)
• Measured-only metrics record today's value and a direction
• Exceptions have an owner and an expiry date
• AGENTS.md or CLAUDE.md points at CONSTRAINTS.md
• A trial run on the current branch produces no failures the user disagrees with