SPEC.md is the project's personal contract

Create SPEC.md before writing code. It reduces uncertainty for the author, Claude, the mentor, and the reviewer, and describes what is being built, what will not be built, and how to prove the result.

CAPSTONE_BRIEF.md contains shared capstone rules, while SPEC.md records your project-specific contract. EVIDENCE.md later stores actual checks, decisions, and scope changes.

Minimal SPEC.md structure
# Project name

## Problem
## Audience
## Current situation
## Expected result
## Scope
## Non-goals
## Constraints
## Acceptance criteria
## Verification plan
## Risks and open questions

Describe behavior, not a desired stack

  • start with a concrete user problem;
  • describe one main scenario;
  • formulate an observable expected result;
  • move integrations, a mobile client, and production deployment to non-goals when they are not needed;
  • record technical and process constraints separately from acceptance criteria.

Acceptance criteria and the verification plan

Criteria must be observable. The verification plan should explain how to confirm each criterion and what to do after an unsuccessful run or test.

PartExample wording
Acceptance criterionThe user can add a subscription and see the next charge
VerificationLocal run, smoke scenario, and checks of dates and statuses
Failure pathAfter a test fails, record the error in EVIDENCE.md and return to the scope

Claude as editor and interviewer

  1. Ask it to find ambiguities in the problem and core flow.
  2. Check for hidden overscope and weak non-goals.
  3. Ask it to identify missing acceptance criteria or checks.
  4. Consider risks and open questions without automatically expanding the project.
  5. Make the decision yourself about what enters SPEC.md.

SPEC.md remains a living document

When the scope, non-goals, or verification method changes, update SPEC.md and record the reason and consequences in EVIDENCE.md. For migration, modernization, DevOps, and workflow projects, the structure stays the same even though the evidence set may differ.

For the Subscription Watch example, the scope can include adding a subscription, listing active subscriptions, showing the next charge, and cancellation. Banking integrations, a mobile application, and AI categorization can be explicitly excluded.

Canonical lesson source · JavaRush

Open JavaRush material