Sections in this lesson

Spec-Driven Development

Turn an ambiguous request into observable acceptance criteria, a small plan and an explicit design decision.

Reviewed: · Content owner: Interview Preparator

What you will learn

  • Write positive, negative and compatibility acceptance cases.
  • Record alternatives and consequences in an ADR.
  • Split a requirement into independently verifiable changes.

Before you start

The flow

  1. 1.Problem
  2. 2.Non-goals
  3. 3.Acceptance cases
  4. 4.ADR
  5. 5.Small tasks
  6. 6.Verification mapping

Specify behavior before implementation detail

“Add a source filter” leaves important questions unanswered: does an empty list mean all sources or none, can a caller select a foreign tenant ID, and what happens when a selected document is not retrieved? Resolve these as observable input/output rules before editing the pipeline.

The case spec keeps omitted/null selection backward compatible, treats an empty list as no evidence, validates at most ten UUIDs and intersects the selection with tenant-authorized top-three candidates. These rules make both compatibility and denial testable.

Use the ADR to preserve a tradeoff

ADR-001 compares post-retrieval intersection with indexing trusted source metadata and filtering before top-K. The first is a small change; the second can improve selected-document recall but brings ingestion and backfill work. Neither is universally superior.

A decision record states context, alternatives, choice and consequences. Explicitly record that an authorized selected source outside the top three may produce ABSTAIN. Avoid calling this selector complete corpus search or an authorization system.

Plan in evidence-sized slices

Start with validation and service compatibility, then selection before prompt creation, then endpoint isolation and eval cases. Each package names its files, acceptance case and verification command; unrelated model upgrades stay out of the diff.

If the implementation reveals an unresolved requirement, update the spec and affected tests together, with owner review. The spec is a versioned agreement, not an immutable prompt whose errors must be preserved.

Try it

spec.md
markdown
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
# RAG-SELECT-001 — Narrow evidence selection / Kaynak seçimini daralt
## Problem / Sorun
An authenticated learner can ask the tutor a question but cannot restrict its evidence to selected source IDs. Add an optional `sourceIds` request field while keeping the existing tenant boundary.
Kimliği doğrulanmış kullanıcı kanıtları seçtiği kaynaklarla sınırlayamıyor. Mevcut tenant sınırını koruyarak isteğe opsiyonel `sourceIds` ekle.
## Acceptance / Kabul
- Omitted or null selection preserves the old behavior. Empty selection abstains before generation.
- At most ten UUID strings; invalid, null list members or oversized lists return HTTP 400.
- Selection intersects the trusted tenant's retrieved top-3 candidates. It never fetches arbitrary IDs or widens authorization.
- Foreign-only and unknown-only selection abstain with no evidence disclosure. Mixed selection returns only authorized selected sources.
- No surviving evidence means zero model calls. Fabricated citations remain rejected.
- Alan yok/null: eski davranış. Boş liste: üretim öncesi ABSTAIN. En çok on UUID; hatalı eleman/liste 400.
- Seçim, güvenilen tenant için bulunan ilk üç adayla kesişir; yeni belge getirmez ve yetki vermez.
## Non-goals / Kapsam dışı
No full-corpus selected-document search, ACL redesign, model migration, database migration, quality benchmark or deployment. This post-retrieval selector can miss a selected source outside the top three; document that limitation.
Tüm korpusta seçilen belgeyi arama, ACL değişikliği, migration, canlı kalite benchmarkı veya deployment yok. İlk üç dışında kalan kaynak bulunamayabilir.
## Work packages / İş paketleri
1. Validate endpoint and direct service callers; retain two-argument service compatibility.
2. Intersect candidates before composing the prompt; retain citation validation.
3. Add no-model-call unit assertions, authenticated MVC/pgvector isolation checks and six versioned before/after eval cases.
4. Refresh bound lesson snippets; run content/lint/build and Java checks; bind evidence to the exact source bundle.
5. Independent human reviews the source bundle and evidence. Release stays pending until external approval and rollback readiness are verified.
## Acceptance evidence / Kabul kanıtı
`RagServiceTest`, `PgVectorRagIT`, `source-selection-cases.json`, generated `target/sdlc-eval.json`, and the local evidence manifest. These prove fixture behavior, not semantic grounding by a live model.

Source: examples/agentic-sdlc/spec.md. Follow examples/agentic-sdlc/README.md to run the case. This is teaching evidence; human release review remains pending.

Interview questions

How would you demonstrate: Write positive, negative and compatibility acceptance cases.

The case spec keeps omitted/null selection backward compatible, treats an empty list as no evidence, validates at most ten UUIDs and intersects the selection with tenant-authorized top-three candidates. These rules make both compatibility and denial testable.

How would you demonstrate: Record alternatives and consequences in an ADR.

A decision record states context, alternatives, choice and consequences. Explicitly record that an authorized selected source outside the top three may produce ABSTAIN. Avoid calling this selector complete corpus search or an authorization system.

How would you demonstrate: Split a requirement into independently verifiable changes.

If the implementation reveals an unresolved requirement, update the spec and affected tests together, with owner review. The spec is a versioned agreement, not an immutable prompt whose errors must be preserved.

Practice

Apply this stage to RAG-SELECT-001 and prepare the handoff for the next owner.

Check your solution

  • Reference one observable acceptance case.
  • Include exact files, commands and remaining risks.
  • Keep review pending until independent approval of the unchanged candidate.

Official references

Continue learning

Category sequence

Agentic SDLC

Lesson 2 / 6

Was this lesson useful?

Change notes: 2026-10-30: Phase 4, source-bound delivery case.