Reading: Part 21. Conclusion and Working System

Lesson 1 of 5 in module «Part 21. Conclusion and Working System»

You are viewing the lesson without signing in. Sign in to save progress and take tests.

Source

Part 21. Conclusion and Working System

SDD is not a set of files for the sake of files. It is a working system that helps a person maintain control when an agent can in minutes change what used to take hours. The main skill is not writing maximally long prompts, but establishing the right boundaries between intent, planning, implementation, and verification.

If leaving only one formula, it is this:

Specification holds long-term intent.
Facts decide whether a branch can be merged.
Agent executes quickly.
Human is responsible for judgment.

Or even shorter:

Specifications guide.
Facts permit merge.

Final Repository Structure

agentclinic/
  AGENTS.md
  QWEN.md
  README.md
  CHANGELOG.md
  package.json
  tsconfig.json
  .qwen/
    settings.json
    hooks/
      pre_tool_guard.py
      log_tool_result.py
      inject_sdd_context.py
    memory/
      agent-memory.db
    skills/
      feature-spec/
        SKILL.md
      changelog/
        SKILL.md
  specs/
    mission.md
    tech-stack.md
    roadmap.md
    2026-05-01-hello-hono/
      requirements.md
      plan.md
      validation.md
    2026-05-02-agents-ailments/
      requirements.md
      plan.md
      validation.md
  src/
  tests/
.github/
  pull_request_template.md

Operational Cycle

Before each feature:

git checkout main
git pull --ff-only
git status --short
npm test
npm run typecheck

In Qwen Code:

/clear
Use the feature-spec skill to start the next feature from the roadmap.
Do not implement code.

After specification:

git add specs/YYYY-MM-DD-feature-name
git commit -m "Add <feature> spec"

Implementation:

/clear
Read @QWEN.md, @specs/mission.md, @specs/tech-stack.md
and @specs/YYYY-MM-DD-feature-name/plan.md.
Implement only task group 1.
Stop after the report on changed files and verification commands.

Verification:

/clear
Compare implementation with @specs/YYYY-MM-DD-feature-name/validation.md.
List confirmed facts, failed facts, missing facts
and ambiguous verification items.
Do not change files.

Merge:

Use the changelog skill to update @CHANGELOG.md for this branch.

npm test
npm run typecheck
git checkout main
git merge <feature-branch>
git branch -d <feature-branch>

Replanning:

/clear

Check @specs/mission.md, @specs/tech-stack.md, @specs/roadmap.md,
recent feature specs and @CHANGELOG.md.
What needs updating before the next feature?
Do not change files until I approve.

Decision Boundaries

Record in mission.md:

audience;
product meaning;
tone;
definition of success.

Record in tech-stack.md:

language;
runtime;
framework;
database;
testing;
deployment constraints;
forbidden or deferred technologies.

Record in roadmap.md:

phase order;
phase status;
small deliverable results;
what counts as the next step.

Record in feature specification:

boundaries and what is out of scope;
decisions specific to this feature;
task groups;
set of facts in validation.md;
verification commands with expected results;
fact statuses: draft, required, implemented, deferred;
manual checks.

Record in QWEN.md or AGENTS.md:

agent behavior rules;
verification commands;
prohibition on speculative refactorings;
requirement to write specifications first, then code.

Most Common Mistakes

Too large a first feature. Start with an infrastructure scaffold, not an MVP.

Specification is written but not used in the implementation request.
Verification is limited to "looks okay" instead of facts.
Replanning is skipped, and specifications become outdated.
Agent is given old chat context instead of files.
Skills are created too early, before understanding the process.
Everything is dumped into QWEN.md, and the agent stops following the main thing.
MCP is connected without a clear task.

How to Adopt in a Real Team

Start not with a 20-page process, but with one rule:

No multi-file feature without requirements.md, plan.md and validation.md.

Then add:

short AGENTS.md;
specs/mission.md;
specs/tech-stack.md;
roadmap for the next 3–5 phases;
one project skill for feature specification;
one skill for changelog;
mandatory checklist in merge request.

After 2–3 features, conduct a retrospective:

where the agent guessed;
which specifications were useless;
which checks caught real errors;
which verification items were wishes, not facts;
what should be automated.

Minimal SDD Template

specs/
  mission.md
  tech-stack.md
  roadmap.md
  YYYY-MM-DD-feature/
    requirements.md
    plan.md
    validation.md

This is enough to start. No need to wait for the perfect framework.

SDD Maturity Scale

To understand where you are and where to move, it is convenient to describe the SDD process in a team by a short scale from 0 to 4. This scale does not claim to be canonical; it helps notice which step will give the most right now.

Level 0 — vibe coding. One long chat with the agent. Decisions remain in session history. No specifications, verification is "see how it works".
Level 1 — specifications appear, but facultatively. For large features the team writes requirements.md, for small ones — not. validation.md more often resembles a wishlist. /clear between roles is forgotten.
Level 2 — SDD as default standard. Any multi-file feature starts with a specification. validation.md contains executable facts. /clear between roles has become a habit. Replanning is conducted between features.
Level 3 — codified process. Repeatable prompts are extracted into skills. Guard hooks automatically check dangerous operations. Review follows four layers (part 16). Antipatterns (part 20) are recognized and quickly fixed.

Level 4 — learnable process. The team regularly turns observations into new rules (part 10, codification step). Agent memory is connected where it is truly useful, and removed where it is redundant. Agent replaceability (part 15) is tested in practice: the team changed the tool and did not lose the process.

Most learning teams are between levels 0 and 2. The goal of the tutorial is to bring your team to level 2 on the didactic AgentClinic project. Levels 3 and 4 are about a specific team, specific product, and specific year. They should not be an end in themselves.

A sign that you have moved from level 1 to 2: a new feature in the team by default starts with a specification, not with a request to "write code".

A sign that you have moved from level 2 to 3: when a recurring agent error appears, someone calmly says "let's add a rule to QWEN.md", and that rule actually appears.

Final Practice

Take your real project and add only:

AGENTS.md or QWEN.md;
specs/mission.md;
specs/tech-stack.md;
specs/roadmap.md;
specification of one small feature.

Ask Qwen Code:

Act as a new agent without previous context.

Read the project SDD artifacts.
Say whether you can safely implement the next feature.
Before writing code, list missing information.

If the agent asks good questions, you are on the right path.