Study guide: Part 6. Creating a Constitution

Topic: Part 6. Creating the Constitution

Difficulty level: Medium

Estimated study time: 3-4 hours (including practice with Qwen Code)

Prerequisites: Basic understanding of Git and command line

Familiarity with TypeScript and Node.js

Experience working with markdown documents

Understanding of SDD (Specification-Driven Development) fundamentals from previous course parts

Access to Qwen Code or a similar AI assistant for practical assignments

Learning objectives: Create a project constitution from three mandatory files (mission.md, tech-stack.md, roadmap.md) before starting development of the first feature

Distinguish between long-term architectural decisions (tech-stack.md) and single-feature-level decisions (requirements.md) using the criterion of surviving five features unchanged

Conduct a structured interview with an AI agent for collaborative constitution creation, asking three grouped blocks of questions

Identify and formalize implicit team rules in QWEN.md based on analysis of git diff after the first feature

Check the constitution for contradictions, vagueness, and phase size before committing

Overview: The Constitution is a project contract between the human, the AI agent, and future project participants that prevents the agent from repeatedly "guessing" the mission, stack, and work order. In the SDD methodology, the constitution is formed before the first product feature and consists of three mandatory files in the specs/ directory: mission.md (why and for whom), tech-stack.md (technical project decisions), and roadmap.md (phased implementation plan). This course part teaches not simply writing these documents by hand, but creating them collaboratively with the agent through a structured interview, checking for contradictions, and extracting implicit rules into explicit conventions. Special attention is paid to the boundary between constitutional decisions and feature specifications, as well as the practice of capturing unwritten team rules in QWEN.md based on real experience interacting with the agent.

Key concepts: Project Constitution: A set of three files (mission.md, tech-stack.md, roadmap.md) in the specs/ directory, formed before the first feature. Works as a contract: if skipped, the agent will guess the mission, stack, and work order anew each time, leading to architectural degradation and loss of integrity.

Mission.md: Answers the questions "why" and "for whom". Contains the product's purpose, primary audience, and success criterion. Example from the course: AgentClinic — a satirical educational application where AI agents are patients at a mental health clinic, and humans invoke their ailments. The code must remain serious and educational.

Tech-stack.md: Captures long-term technical project decisions: language, runtime environment, web framework, DBMS, testing library, dependency constraints. Key principle: decisions here must survive at least five features without changes. Each change triggers replanning (course part 10).

Roadmap.md: A short roadmap broken into small phases, each fitting in one focused branch. Phases must be small enough to be verifiable without heroics. Example: Phase 1 only proves the basic connection works, Phase 2 adds domain data.

Tech-stack.md / requirements.md boundary: The fundamental separation rule: tech-stack.md holds project-level decisions (survive five features), requirements.md for features holds single-feature-level decisions (routes, form fields, validation rules). Simple test: if a decision will be forgotten after feature merge — it goes in requirements.md. Example: "use Hono" — tech-stack.md; "route GET /agents returns HTML with a list of 10 records" — feature requirements.md; "all lists return 10 records by default" — tech-stack.md or conventions.md.

Qwen.md and implicit rules: A document for capturing unwritten team rules that the agent consistently guesses incorrectly. Typical areas: code style and naming, forbidden constructs (any, @ts-ignore), allowed dependencies list, error message format, error handling structure, commit format, pre-merge rituals. The best way to identify them — analyze git diff after the first feature and find style fixes or decisions made for the agent.

Interview via qwen code: A structured process for collaborative constitution creation: the agent is given context, asks exactly three grouped questions (mission and audience, technical stack, roadmap), receives specific decisions in response, not general wishes, and only then writes the files. If the agent skips the interview — it must be stopped and required to follow the protocol.

Constitution verification: A mandatory step before commit: the agent checks its own files for contradictions, vague formulations, and overly large phases. Typical problems: roadmap requires heroics, stack contains "just in case" dependencies, mission.md doesn't define the code reader, SQLite mentioned in roadmap but not in stack, "modern interface" without specific constraints.

Practice exercises: Name: Exercise 1: Decision Classification — Where to Record?

Problem: Five technical decisions are given for the AgentClinic project. Determine for each which document it belongs to: tech-stack.md, feature requirements.md, or roadmap.md. Justify using the "survives five features" criterion.

1. Use the Hono library for the web framework
2. Route POST /appointments accepts fields agentId, ailmentId, date and returns 201 with record ID
3. Add Prisma ORM for database work
4. Phase 2: add therapies table and /therapies page
5. All forms on the site use server-side validation with errors returned in one format

Solution: 1. tech-stack.md — web framework choice determines the architecture of the entire project, will survive many features.

1. requirements.md for feature "Appointment Booking" — specific route, fields, and response code belong to one feature, will be forgotten after implementation.
2. tech-stack.md — ORM choice is a long-term architectural decision, affects all data access layers.
3. roadmap.md — this is a roadmap phase, not a technical decision or feature details.
4. tech-stack.md (or separate conventions.md) — validation rule for all project forms, will survive many features. If it were only about the appointment booking form — it would be requirements.md.

Complexity: beginner

Name: Exercise 2: Composing mission.md for a New Project

Problem: You are starting the "DevGarden" project — a platform for visualizing developer skill growth in the form of a garden of plants. Each commit waters a plant, skipping a day causes withering. Write a complete mission.md file including: purpose (satirical or serious tone?), primary audience (minimum 2 groups), success criterion. Follow the structure from the course.

Solution: Example answer:

# Mission

DevGarden — a platform that transforms a developer's commit history into a living garden: regular activity waters plants, breaks lead to withering.

## Purpose

The product is a motivational tool with gamification elements. The premise is delivered in a semi-serious tone: plants react to real activity in repositories, and withering is a vivid metaphor for "technical debt" in the attention reservoir.

## Primary Audience

- Developers studying SDD with agents that write code.
- Teams implementing gamification of development metrics.
- Engineers studying integration with GitHub API and server-side TypeScript applications.

## Success

The developer should understand how SDD artifacts help maintain a unified product metaphor across many features, and be able to expand the garden with new plant types without losing architectural integrity.

Check: is there an answer to "why" (motivation through metaphor), "for whom" (3 groups), specific success criterion (understanding the role of SDD artifacts, not just "the application works").

Complexity: intermediate

Name: Exercise 3: Analyzing git diff to Create QWEN.md

Problem: After the first feature with the agent, you discovered in git diff the following fixes made manually for the agent:

• Agent used console.log for DB errors → you replaced with a structured logger with levels
• Agent named variable usrData → you renamed to userData
• Agent placed // @ts-ignore before SQLite query → you removed and added correct typing
• Agent wrote commit "some fixes" → you rewrote to "fix(db): handle connection timeout in agent repository"
• Agent added lodash dependency for one debounce function → you replaced with native implementation

Formulate 3-5 rules for QWEN.md based on these patterns.

Solution: Example QWEN.md:

# QWEN.md — Project Conventions for AgentClinic

## Logging
- Direct `console.log` and `console.error` are forbidden in production code
- Use unified structured logger with levels (info, warn, error, debug)
- DB error messages must include operation context, not expose sensitive data

## Naming
- Abbreviations are forbidden: `usr`, `data`, `cnt` → use `user`, `data`, `count`
- camelCase for variables and functions, PascalCase for classes and interfaces, snake_case for DB fields

## TypeScript
- `any` and `// @ts-ignore` are forbidden in production code
- Every DB query must have explicit result typing

## Commits
- Format: `<type>(<<scope>): <verb in present tense> + <object>`
- Examples: `feat(agents): add list endpoint`, `fix(db): handle connection timeout`
- Commits like "fix", "update", "some changes" are forbidden

## Dependencies
- New dependency requires discussion and tech-stack.md update
- Prefer native solutions over libraries for simple tasks (debounce, throttle, deep clone of simple objects)

Key skill: transforming observable error patterns into concrete, verifiable rules, not general recommendations.

Complexity: intermediate

Name: Exercise 4: Checking Constitution for Contradictions

Problem: A draft constitution for a project is given. Find at least 4 problems that the verification step before commit should identify.

# mission.md
AgentClinic — a clinic for AI agents. Educational app for everyone.

# tech-stack.md
- TypeScript
- Hono
- SQLite (local storage)
- ORM Prisma
- React for UI
- Vitest

# roadmap.md
## Phase 1
- Install all dependencies
- Set up database with migrations
- Create all tables (agents, ailments, therapies, appointments)
- Implement all routes (GET, POST, PUT, DELETE)
- Add administrator authentication
- Write tests for everything

Solution: Identified problems:

1. Vague mission: "for everyone" — not a specific audience, no success criterion, tone unclear (satirical/serious).

1. Contradiction in stack: React for UI is listed in tech-stack.md, but in the course and typical AgentClinic approach server-side Hono JSX rendering is used — needs clarification whether React is a deliberate deviation from the course methodology.

1. SQLite in roadmap but not in stack: SQLite is mentioned in tech-stack.md (OK), but ORM Prisma is added without justification — the course explicitly states "direct SQL migrations until ORM appears", meaning ORM comes later, not at the start.

1. Phase 1 requires heroics: 6 items, including "everything" — all route types, authentication, tests for everything. This violates the principle "each phase in one branch, verifiable without heroics". Should be split into 3-4 phases.

1. "Just in case" dependency: Administrator authentication in the first phase of an educational satirical app — possibly premature complexity, not justified by the mission.

1. No constraints in stack: missing rules for adding dependencies, no ban on "just in case".

Complexity: advanced

Case studies: Name: Case: How a Team Lost Three Iterations Due to Missing mission.md

Scenario: A team of three developers started the "EcoTrack" project — an app for tracking carbon footprint. The tech lead quickly wrote tech-stack.md with React Native and Firebase, and made a roadmap with three large phases of two months each. They considered mission.md unnecessary — "it's obvious, ecology and all that".

Challenge: After the first iteration, it turned out the developers understood the product differently: one made a B2C app for eco-friendly shopping, the second — a corporate dashboard for ESG reporting, the third — a gamified tracker for schoolchildren. Conflicting additions appeared in tech-stack.md: Mapbox for store maps, Tableau integration for reports, Unity for game mechanics. The agent (Claude Code) asked basic questions anew with each feature and generated code for different audiences in different parts of the app.

Solution: The team stopped development, conducted a joint session with the agent through a structured interview. mission.md was created with a clear definition: "EcoTrack — B2B SaaS for medium companies (50-500 employees) that need to automate data collection for ESG reporting under GRI standard. Tone: business-like, no gamification". The technical stack was cleaned of Mapbox and Unity, with the constraint "new integration requires ROI justification for the target company" added. The roadmap was broken into phases of one-two weeks: Phase 1 — prototype Excel data import, Phase 2 — basic metrics calculation, Phase 3 — GRI report generation.

Result: After constitution implementation, development speed increased by 40% (by story points per sprint metric). The agent stopped "guessing" and started proposing solutions within the given architecture. Code review shrank from 15 "why is this here?" comments to 2-3 technical remarks. After 4 months the product launched with three pilot companies.

Lessons learned: mission.md is not "fluff", but a filter for all subsequent decisions: without it even a good tech-stack.md erodes under pressure of uncertainty

Interview with the agent works as a team convergence catalyst: forces formulation of implicit agreements explicitly

Large phases mask uncertainty: if a phase cannot be verified within a week, it hides unworked risks inside

The agent as a "mirror" reflects chaos in the project: if it constantly "guesses" differently, the problem is not the agent but the missing constitution

Related concepts: mission.md

Interview via Qwen Code

Tech-stack.md / requirements.md boundary

Constitution verification

Name: Case: How One Developer Created QWEN.md After First Feature and Saved 20 Hours

Scenario: Indie developer Anna started the "BookShelf" project — a service for exchanging books in the neighborhood. She used Qwen Code to accelerate development. After the first feature (registration and profile), she noticed she spent a lot of time fixing the code style returned by the agent.

Challenge: Git diff analysis showed 47 manual fixes in 12 commits: the agent used different naming styles (snake_case vs camelCase), added any for "simplicity", wrote commits mixing Russian and English, used console.log instead of the configured pino logger. Each new feature required repeating this fix cycle.

Solution: Instead of continuing "manual" control, Anna spent 2 hours creating QWEN.md based on patterns from git diff. The document included: a mapping table of contexts and naming styles (DB — snake_case, code — camelCase), ban on any with alternative typing patterns, commit template with examples, requirement to use pino with logging level from config. She also added a "Pre-merge ritual" section: run linter, type check, and one happy path test.

Result: In the second feature, manual fixes dropped from 47 to 3 (all logical, not stylistic). Time for self code-review of her own PRs shrank from 45 minutes to 5. The agent started generating commits in the correct format independently. After three features, Anna expanded QWEN.md with the rule "new dependency is discussed" — the agent proposed adding lodash, and she rejected it, replacing with native implementation, which reduced the bundle by 12 KB.

Lessons learned: git diff after first feature — a free audit of implicit rules: every manual fix is a candidate for QWEN.md

QWEN.md pays for itself in one feature: 2 hours of writing vs 20+ hours saved on subsequent iterations

Concrete examples in QWEN.md matter more than abstract rules: "use pino" is worse than "use pino with level from config.logLevel, not console.log"

QWEN.md is a living document: it grows with the project, but starts from real pains, not assumed ones

Related concepts: QWEN.md and implicit rules

Constitution verification

Tech-stack.md / requirements.md boundary

Study tips: Go through the material sequentially: first understand "why the constitution", then study each file's structure, then practice the interview with the agent. Skipping a step leads to formal document creation without understanding their role.

Use the "parallel reading" method: open the original course document and examples from practice_exercises simultaneously, compare structure. This strengthens pattern recognition for independent work.

Be sure to do Exercise 4 (contradiction check) with a timer: limit yourself to 10 minutes, as in real code review. Time pressure trains identification of critical problems instead of "perfect" analysis.

Create constitution file templates in your editor with placeholders like [PURPOSE], [PRIMARY_AUDIENCE_1]. Use them for every new project — the physical ritual accelerates internal methodology adoption.

Keep an "agent interview diary": record what questions the agent asked, what answers you gave, what went wrong. After 3-4 projects you'll form a personal library of "classic traps" and effective formulations.

For kinesthetics: print a physical card with the "survives five features" criterion and place it next to your monitor. For each decision physically move the card: "to stack?" — place on tech-stack.md, "to feature?" — on requirements.md.

For auditories: speak aloud the constitution verification steps before commit: "Is SQLite in the stack? Do phases fit in branches? Does mission say who reads the code?" — speech rhythm creates a mnemonic anchor.

For visuals: draw a "decision lifecycle" diagram — from idea emergence through the "five features" test to final place in documentation. Color coding (red — tech-stack.md, blue — requirements.md, green — roadmap.md) speeds up real-time decision making.

Additional resources: Original course document (part 6): Source material this guide is based on — refer for clarifying details and code examples

Hono documentation: https://hono.dev — minimal web framework recommended in the course for server-side TypeScript

Conventional commits: https://www.conventionalcommits.org — commit format standard, typical element of QWEN.md

SQLite on node.js: https://github.com/WiseLibs/better-sqlite3 — popular driver for working with SQLite without ORM, matches the course philosophy

Vitest: https://vitest.dev — testing framework mentioned in tech-stack.md examples

Gitlab mission.md template: https://about.gitlab.com/handbook/engineering/ux/technical-writing/workflow/#documentation-templates — alternative approaches to structuring product mission

"Architecture decision records" article: https://adr.github.io — related practice of capturing long-term decisions, extends understanding of tech-stack.md role

Summary: The Constitution is the heart of an SDD project: three files (mission.md, tech-stack.md, roadmap.md), created before the first feature, prevent the agent's chaotic "guessing" and ensure architectural integrity. Key skills of this part: distinguish long-term decisions (stack) from feature decisions (requirements) using the "five features" test; conduct a structured interview with the agent instead of manual writing; identify implicit rules through git diff analysis and capture in QWEN.md; check the constitution for contradictions and phase size before commit. Practice shows: 2 hours on constitution and QWEN.md save 20+ hours on subsequent iterations. The Constitution lives — it grows with the project, but its absence at the start guarantees architectural debt.