Topic: Part 5. Initial Project Setup
Difficulty level: Medium
Estimated study time: 2-3 hours (theory + practice)
Prerequisites: Basic knowledge of command line (bash/zsh)
Understanding of Git fundamentals (init, add, commit, status)
Familiarity with Node.js and npm (installing packages, package.json)
Basic TypeScript knowledge (tsconfig, compilation)
Understanding of the .gitignore concept
Learning objectives: Independently create a minimal SDD scaffold: Git repository, TypeScript project with strict mode, basic folder structure, and starter documents
Configure the Knowledge Priming system for the agent via QWEN.md and understand which files the agent should read before starting work
Distinguish initial setup from premature implementation of product features and be able to explain why frameworks and databases are deferred to the constitution phase
Verify repository readiness via Qwen Code and correctly interpret its recommendations without allowing premature changes
Overview: Initial project setup in the SDD (Specification-Driven Development) methodology is creating a minimal, clear, and safe foundation for subsequent agent work. Unlike traditional development, where at this stage one often "immediately builds the application," in SDD the initial setup task is more modest: prepare the workspace, establish Git boundaries, create a Knowledge Priming mechanism, and capture the initial wishes of participants. This phase does not include choosing web frameworks, configuring databases, implementing APIs or product routes — all these decisions are deliberately deferred until the project constitution is created (mission.md, tech-stack.md, roadmap.md). The study project AgentClinic — a fictional mental health clinic for AI agents — serves as a practical model for mastering these principles. Upon completion of this phase you will have: a Git repository, README.md with product vision, QWEN.md with agent behavior rules, .qwen/settings.json configuration, minimal TypeScript stub with empty src/index.ts, package.json with typecheck script, tsconfig.json with strict: true, and the first commit with a meaningful message.
Key concepts: SDD scaffold: The minimal project structure sufficient to begin specification work. Includes only infrastructure elements without product logic. Analogous to scaffolding before building walls — not a house, but a safe working platform.
Knowledge priming: The practice of preloading critically important contextual knowledge at the start of every agent work session. In corporate texts this refers to fixing mandatory reading files in QWEN.md, so the agent doesn't waste tokens guessing the project structure. This is fundamentally different from ad-hoc prompting: rules are formalized and repeatable.
Project constitution: Three documents — specs/mission.md (why the project exists), specs/tech-stack.md (what stack and why), specs/roadmap.md (what is the current phase and what's next). Created after initial setup, but before then the agent must know of their future existence via QWEN.md.
Strict TypeScript mode: Configuration of strict: true in tsconfig.json, mandatory for SDD projects. Prevents implicit any, optional null checking, and other sources of runtime errors. At the initial setup phase this is an investment in the reliability of all subsequent specifications.
Git commit boundary: The practice of meaningful commit after completing a phase. The first commit "Initialize AgentClinic scaffold" creates a clear historical point: before it — infrastructure, after — constitutional work begins. Helps with rollbacks and tracking when decisions were made.
Premature implementation: The anti-pattern when an agent or developer at the initial setup phase begins writing business logic, choosing frameworks, or designing databases. In SDD this violates the principle of deferred decisions: infrastructure is separated from product decisions in time.
Rule of three things: Before the first action, the agent must know three main things: why the project exists (mission), what stack (tech-stack), and what is the current phase (roadmap). This is the minimal context for meaningful work.
Practice exercises: Name: Creating a scaffold from scratch
Problem: You've been assigned to start the AgentClinic study project in a new folder. Execute all initial setup commands: create folder structure, initialize Git and npm, install TypeScript, create all necessary files. Then verify that npm run typecheck passes without errors, and git status shows only untracked files that should be in .gitignore.
Solution: 1. mkdir agentclinic && cd agentclinic
- git init
- npm init -y
- npm install -D typescript @types/node
- npx tsc --init
- mkdir -p src specs .qwen
- touch src/index.ts
- Edit tsconfig.json: set "strict": true
- In package.json add script "typecheck": "tsc --noEmit"
- Create .gitignore with content from course materials (node_modules/, dist/, build/, .env, .env., .qwen/memory/, .idea/, .vscode/)
- Create README.md with project vision
- Create QWEN.md with Knowledge Priming block
- Create .qwen/settings.json (empty or with safe configuration)
- Verify: npm run typecheck (should pass with empty src/index.ts)
- Verify: git status (node_modules should not appear as untracked)
- git add README.md QWEN.md package.json package-lock.json tsconfig.json src .qwen
- git commit -m "Initialize AgentClinic scaffold"
Complexity: beginner
Name: Analyzing a request for premature implementation
Problem: A colleague sent you a prompt for an agent: "Build the AgentClinic application. Set up Hono for API, connect SQLite via Drizzle, make tables for agents and therapies, implement CRUD routes. Use TypeScript with strict mode." Explain what in this request violates SDD initial setup principles, and rewrite the request according to the methodology.
Solution: Violations in the original request:
- "Build the application" — mixes infrastructure and product logic
- "Set up Hono" — choosing web framework at a stage when there is no constitution yet
- "Connect SQLite via Drizzle" — choosing ORM and DB before tech-stack.md
- "Make tables" — data schema without specification
- "Implement CRUD routes" — product routes before mission.md
Rewritten request: "Prepare the repository for SDD for the AgentClinic project. Don't choose a web framework yet — we'll defer that decision to specs/tech-stack.md. Don't implement product routes — we'll first create specs/mission.md.
Ensure that:
- Git repository is initialized
- TypeScript is configured with strict: true
- There is a typecheck script in package.json
- Folders src/, specs/, .qwen/ are created
- QWEN.md contains Knowledge Priming rules
- README.md reflects product vision
- .gitignore excludes build artifacts and secrets
Everything related to Hono, SQLite, Drizzle and business logic — record as open questions for subsequent phases."
Complexity: intermediate
Name: Repository diagnostics via Qwen Code
Problem: You've completed initial setup, but when checking via Qwen Code the agent suggested: "Let's immediately add Hono for the future API, this will speed up development. And I see you don't have tests — I'll install Vitest." Your task: formulate a response to the agent that stops premature actions while maintaining a constructive tone, and explain why these suggestions go beyond the current phase.
Solution: Response to agent: "Thank you for the initiative, but let's adhere to SDD phasing.
Hono: choosing a web framework is a product decision that should go into specs/tech-stack.md with justification. We don't even have specs/mission.md yet, so we don't know if we need an HTTP server at all (the project might be a CLI utility or library). Let's defer to the constitution phase.
Vitest: testing is important, but testing strategy (unit, integration, e2e) depends on architecture we haven't designed yet. Adding Vitest now will create an illusion of readiness to test what isn't specified. Let's record in roadmap.md as a task after creating the first feature specification.
Current task: verify only infrastructure. Confirm that:
- strict TypeScript mode works
- Git repository is clean
- QWEN.md contains Knowledge Priming rules
- All initial setup files are in place
If everything is in order — complete the session without changes."
Complexity: intermediate
Name: Security audit of .qwen/settings.json
Problem: The following lines appeared in your .qwen/settings.json: { "model": "qwen-coder-plus-latest", "apiKey": "sk-qwen-2b3c...9f4a", "temperature": 0.7 } Analyze the problem, determine the correct action, execute it, and explain why the model configuration can remain in the repository while apiKey cannot.
Solution: Problem: apiKey is a secret that must not be committed to Git. Even in private repositories this violates the principle of least privilege and creates leakage risk upon cloning, forking, or accidental publication.
Actions:
- Immediately revoke the key via the API provider's control panel
- Remove the key from .qwen/settings.json
- Add apiKey to .gitignore as a pattern (optional: "apiKey" or more specific)
- Move the key to environment variable: export QWEN_API_KEY=sk-... in .env
- .env added to .gitignore (should already be there)
- Update documentation: indicate that key is passed via QWEN_API_KEY
- Commit only the corrected .qwen/settings.json
Why model can stay: model name is team configuration, it is not sensitive, doesn't grant resource access, and helps all developers use the same version. This is analogous to "node": "20" in package.json — a declarative requirement, not a secret.
Why apiKey cannot: this is a credential granting access to paid resources. Committing it is equivalent to publishing a password.
Complexity: advanced
Case studies: Name: Team "Quick Start" and the technical debt of constitution
Scenario: Startup HealthAI decided to develop a telemedicine platform. A team of three developers got access to Claude Code and decided "not to waste time on bureaucracy." In the first week they created a repository, immediately installed Next.js, Prisma, PostgreSQL, set up authentication via Auth0, and even made an appointment booking prototype. All of this was committed to main without intermediate stages.
Challenge: Two weeks later the investor demanded a pivot: the product must become a B2B platform for corporate clinics, not a B2C service for private patients. It turned out that: Next.js with server components was unsuitable for the required microservices architecture; Prisma ORM created tight coupling with a schema optimized for B2C; Auth0 with corporate SSO required a different licensing plan; appointment booking as a feature was dropped entirely — an API for integration with existing HIS systems was needed instead. The team spent 6 weeks on refactoring instead of 3 days on a new constitution.
Solution: A parallel project in the same company (analytics module) applied SDD with proper initial setup. They: created a scaffold in 2 hours; spent 3 days on specs/mission.md, tech-stack.md, roadmap.md with product manager involvement; got constitution approval from the investor; and only then started implementation. When a similar pivot request came — changes only affected specs/, and infrastructure adapted in a day.
Result: Project "Quick Start" hit the market 4 months later than the competitor with SDD approach, missed the key window, and was shut down. The analytics module became the core of the surviving platform. Internal retrospective revealed: 73% of "Quick Start" technical debt arose before writing the first specification.
Lessons learned: Premature framework choice creates "frozen decisions" that are expensive to thaw
Absence of constitution makes reasoned refusal of features during pivot impossible — everything seems "already invested"
2 hours of boring initial setup save 6 weeks of refactoring
Investors and stakeholders perceive constitution as a document for discussion, but code as a fait accompli
Related concepts: Premature implementation
SDD scaffold
Project constitution
Git commit boundary
Name: Enterprise adoption of Knowledge Priming at a bank
Scenario: A large bank deployed agents for maintaining legacy COBOL systems. 200 developers worked with different agents in different teams. Problem: every session started with 10-15 minutes of "warm-up" when the agent guessed the structure of a monorepo with 40 microservices, often erring and suggesting irrelevant refactorings.
Challenge: Time loss scaled catastrophically: 200 developers × 2 sessions per day × 12 minutes = 80 person-hours per day on "getting up to speed." Meanwhile agents periodically "hallucinated" architecture, suggesting to migrate non-existent services or ignoring critical regulator constraints.
Solution: The platform engineering team created a unified initial setup scaffold for all microservices: standard QWEN.md with Knowledge Priming block, mandating reading of service-manifest.yaml (analog of specs/mission.md), compliance-rules.md (regulatory constraints), and current-sprint.md (active specification). .qwen/settings.json was standardized and stored in a central templates repository. When starting work with any service, the developer cloned the template, and the agent immediately received correct context.
Result: "Warm-up" time reduced from 12 to 2 minutes. Architecture hallucinations decreased by 87% per code quality metrics (fewer review rollbacks). The template became mandatory for all new services, and legacy retrofit took 3 months instead of planned 9.
Lessons learned: Knowledge Priming scales only with standardization of initial setup
Regulatory constraints must be in mandatory reading — agents don't intuitively understand compliance
Centralized .qwen/settings.json template prevents configuration drift between teams
Time savings on warm-up compensate for template infrastructure investment within 2-3 weeks
Related concepts: Knowledge Priming
Rule of three things
SDD scaffold
Study tips: Go through the material twice: first time — follow commands literally, creating an identical scaffold; second time — after a week, create a new project with a different name to test memory and understanding of the sequence
Keep a "deferred decisions diary": every time you're tempted to "immediately add a feature," write down what you wanted to add and why it's premature. Check back in a month — were these decisions correctly deferred?
Use the "red team" method: ask a colleague or imaginary opponent to attack your scaffold with prompts "let's immediately..." and practice responding with convincing refusal explaining phasing
For visual learning style: draw a state transition diagram for the project (scaffold → constitution → feature specification → implementation) and mark which files appear at each phase
For auditory style: dictate commands aloud before executing — this activates other memory channels and helps catch errors
For kinesthetic style: physically delete files and recreate the scaffold from scratch at least 3 times until commands enter muscle memory
Create an "anti-temptation" checklist — a list of things NOT to do at this phase, and hang it near your workspace
Practice explaining the concept of "boring initial setup" to others: the ability to simply and convincingly explain why it's important is the best indicator of understanding
Additional resources: Official TypeScript documentation — tsconfig.json: https://www.typescriptlang.org/tsconfig — reference for all compiler options, especially the strict section
Git book — branching basics: https://git-scm.com/book/en/v2 — chapter on commits and history for understanding Git boundaries
"Architectural decision records" (ADR) pattern: https://adr.github.io/ — methodology for recording deferred decisions, related to SDD constitution
Article "knowledge priming for llm agents": Conceptual foundation of the practice, recommended search by term in academic databases for deep dive
Qwen Code documentation: https://github.com/QwenLM/qwen-code — current recommendations for QWEN.md and .qwen/settings.json
Interactive Git trainer: https://learngitbranching.js.org/?locale=en_US — for reinforcing understanding of commits as phase boundaries
Course "specification-driven development": Full course from which this material is taken — for context of subsequent parts
Summary: Initial setup in SDD is the discipline of creating a minimal but reliable foundation for subsequent specification work. Its key principles: separating infrastructure from product decisions in time; formalizing context for the agent via Knowledge Priming; strict TypeScript mode as a quality investment; meaningful Git boundaries as phase fixation points. The anti-pattern is premature implementation, when "boring" setup turns into "build the application." Properly executed phase yields: Git repository, README.md, QWEN.md with primary reading rules, .qwen/settings.json, TypeScript scaffold with strict: true, package.json with typecheck, and first commit. Everything else — frameworks, databases, business logic — is deliberately deferred until project constitution creation (mission, tech-stack, roadmap) and subsequent feature specifications. The savings from "boringness" at this phase is measured in weeks saved on refactoring when requirements change.