Build Your First Agentic Workflow with Claude and VS Code
Introduction
In the previous article, AI Automation, Agentic Workflows and WAT Explained, we learned how an agentic system can combine:
Workflow + Agent + Tools = WAT
Now we will turn that concept into a real development project.
In this tutorial, we will use VS Code as our development environment and Claude Code as our AI development agent.
Instead of repeatedly asking Claude to generate individual pieces of code, we will create a structured system where Claude can:
- understand our product goal,
- read our development workflow,
- inspect the project,
- make reasonable technical decisions,
- create and modify files,
- run commands,
- run tests,
- examine failures,
- and improve its work.
Our project will eventually become StyleFlow, an online clothing store.
In this article, however, our main goal is to build the agentic development environment that will later build StyleFlow.
1. What Are We Building?
Before writing application code, we need to separate three things:
PRODUCT
What do we want to build?
WORKFLOW
How should development progress?
AGENT
Who will perform and coordinate the work?
For our project:
Product
↓
StyleFlow online clothing store
Workflow
↓
Understand → Plan → Build → Test → Review
Agent
↓
Claude Code
Tools
↓
VS Code
Files
Terminal
Git
Testing tools
Database
This creates our first practical WAT development environment.
2. The StyleFlow Business Goal
StyleFlow will eventually become an online clothing-store platform.
Customers should be able to:
- browse clothing,
- search products,
- view product information,
- select sizes,
- add products to a shopping cart,
- checkout,
- and create orders.
Store administrators should eventually be able to:
- manage products,
- manage inventory,
- view orders,
- and manage customers.
Later, we can expand StyleFlow into a SaaS product that could support multiple clothing stores.
For now, however, we will begin with a manageable Version 1.
3. Create the Project Folder
On Windows, create the following folder:
C:\Utvecklingprogram\AI\styleflow-wat
You can create it manually in File Explorer or through PowerShell.
For example:
cd C:\Utvecklingprogram\AI
mkdir styleflow-wat
cd styleflow-wat
Then open the folder in VS Code:
code .
VS Code should now open:
styleflow-wat
At this point the folder can be empty.
That is intentional.
We want to create the instructions first before asking Claude to build the application.
4. Our Initial Project Structure
We will begin with only a few important files:
styleflow-wat/
│
├── PRODUCT.md
├── WORKFLOW.md
├── CLAUDE.md
└── README.md
Later the project will grow.
For example:
styleflow-wat/
│
├── PRODUCT.md
├── WORKFLOW.md
├── CLAUDE.md
├── README.md
│
├── skills/
├── docs/
├── tests/
│
└── application files...
But we should not create everything at once.
The first three files are especially important.
5. PRODUCT.md — Tell the Agent What to Build
Create:
PRODUCT.md
This document describes the business and product requirements.
Add:
# StyleFlow Product
## Business Goal
Build a modern online clothing store that can later
be developed into a reusable SaaS platform for
independent clothing retailers.
## Target Users
Customers who want to browse and purchase clothing online.
Store administrators who need to manage products and orders.
## Version 1 Features
Customers must be able to:
- browse products
- search products
- browse categories
- view product details
- select a size
- select quantity
- add products to a shopping cart
- modify the shopping cart
- enter checkout information
- create an order
Administrators must be able to:
- view products
- add products
- edit products
- view orders
## Product Information
Each product should contain:
- name
- description
- price
- category
- available sizes
- stock quantity
- image
- active/inactive status
## Technical Requirements
The application must:
- work on desktop and mobile
- use persistent database storage
- validate user input
- contain automated tests
- protect application secrets
- provide useful error handling
## Version 1 Definition of Done
Version 1 is complete when:
1. Products can be displayed.
2. Product search works.
3. Shopping cart works.
4. Checkout creates an order.
5. Administrator can view orders.
6. Information persists in the database.
7. Important automated tests pass.
8. README explains how to run the application.
Why Do We Need PRODUCT.md?
We are separating:
WHAT
from:
HOW
PRODUCT.md describes what the business needs.
It does not say:
Use Flask.
Create app.py.
Use SQLite.
Create exactly seven routes.
Those are implementation decisions.
We want to give Claude some freedom to make reasonable technical decisions.
That is one of the characteristics of agentic development.
6. WORKFLOW.md — Tell the Agent How Work Should Progress
Now create:
WORKFLOW.md
This is the W in our WAT model.
Add:
# StyleFlow Agentic Development Workflow
## Goal
Transform the requirements in PRODUCT.md into a
working, tested and documented application.
## Phase 1 — Understand
1. Read PRODUCT.md.
2. Read CLAUDE.md.
3. Inspect the existing repository.
4. Identify the requirements.
5. Identify missing or unclear information.
## Phase 2 — Plan
6. Design an appropriate architecture.
7. Consider reasonable technology choices.
8. Design the database.
9. Design the application structure.
10. Create an implementation plan.
## Phase 3 — Implement
11. Create the required project structure.
12. Implement persistent storage.
13. Implement backend functionality.
14. Implement the user interface.
15. Implement product browsing.
16. Implement search.
17. Implement shopping cart.
18. Implement checkout.
19. Implement basic administration.
## Phase 4 — Test
20. Run the application.
21. Run automated tests.
If a test fails:
- inspect the failure
- determine the likely root cause
- inspect relevant code
- correct the implementation
- run the test again
Repeat when reasonable until the tests pass.
## Phase 5 — Review
22. Review user experience.
23. Review validation.
24. Review error handling.
25. Review security-sensitive areas.
Correct important problems discovered during review.
## Phase 6 — Finish
26. Run the complete test suite.
27. Update README.
28. Document important technical decisions.
29. Report completed work and remaining limitations.
Now our workflow has a clear progression:
Understand
↓
Plan
↓
Implement
↓
Test
↓
Review
↓
Finish
7. Make the Workflow Agentic
So far our workflow still looks somewhat like traditional automation.
Now we give the agent controlled decision-making authority.
Add the following to WORKFLOW.md:
## Agent Decision Policy
The agent may make normal development decisions
without requesting approval for every small change.
For important technical decisions:
1. Identify reasonable alternatives.
2. Compare their advantages and disadvantages.
3. Select the simplest maintainable solution.
4. Record significant decisions in docs/decisions.md.
5. Continue implementation.
Prefer simple solutions.
Do not introduce unnecessary infrastructure,
frameworks or dependencies.
If a decision could cause data loss, security problems,
financial consequences or production changes,
request human approval before continuing.
This changes the relationship between us and Claude.
Instead of:
Human decides every implementation detail
↓
Claude writes requested code
we move toward:
Human defines goal and boundaries
↓
Claude analyses possibilities
↓
Claude makes normal technical decisions
↓
Claude documents important decisions
↓
Human controls high-impact actions
That is much closer to an agentic workflow.
8. CLAUDE.md — Give Claude Project Instructions
Now create:
CLAUDE.md
This file provides project-level guidance for Claude Code.
Add:
# StyleFlow Development Instructions
You are the primary development agent for StyleFlow.
## Main Goal
Build the product described in PRODUCT.md.
Follow WORKFLOW.md.
## Before Making Changes
1. Read relevant project files.
2. Understand the existing implementation.
3. Identify dependencies.
4. Create a short plan for substantial changes.
## Development Principles
- Prefer simple maintainable solutions.
- Avoid unnecessary complexity.
- Keep business logic separate from presentation.
- Validate external input.
- Handle errors explicitly.
- Never hardcode passwords or API secrets.
- Use environment variables for secrets.
- Write tests for important business behaviour.
- Keep documentation current.
## Testing
After implementing important functionality:
1. Run relevant tests.
2. Inspect failures.
3. Correct implementation problems.
4. Run tests again.
Do not report functionality as complete simply
because code was generated.
## Documentation
Record significant architecture decisions in:
docs/decisions.md
Keep README.md updated with:
- installation
- configuration
- how to run
- how to test
## Human Approval Required
Stop and request human approval before:
- production deployment
- deleting production data
- making real payments
- changing payment configuration
- sending mass email
- publishing externally
- committing passwords, API keys or other secrets
## Completion
When a task is complete, report:
- what was created
- important decisions
- tests performed
- test results
- known limitations
- recommended next step
This becomes Claude’s operating guidance for our project.
9. Understanding the Three Files
We now have:
PRODUCT.md
WORKFLOW.md
CLAUDE.md
They serve different purposes.
PRODUCT.md
Answers:
What are we building?
StyleFlow
Online clothing store
Products
Search
Cart
Checkout
Orders
Admin
WORKFLOW.md
Answers:
How should development proceed?
Understand
↓
Plan
↓
Implement
↓
Test
↓
Review
↓
Finish
CLAUDE.md
Answers:
What rules should Claude follow while working?
For example:
Prefer simple solutions.
Test important functionality.
Never expose secrets.
Ask before production deployment.
Together:
PRODUCT.md
│
▼
WHAT TO BUILD
WORKFLOW.md
│
▼
HOW WORK PROGRESSES
CLAUDE.md
│
▼
AGENT RULES
│
▼
CLAUDE CODE
│
▼
TOOLS
This is our WAT architecture beginning to take shape.
10. Initialize Git
Before allowing an agent to make many changes, version control is extremely useful.
From the VS Code terminal:
git init
Then create:
.gitignore
For a future Python application, it could initially contain:
.venv/
__pycache__/
*.pyc
.env
*.db
.pytest_cache/
The .env line is particularly important.
Secrets should not be committed to Git.
Check the repository:
git status
Then create the first commit:
git add .
git commit -m "Create StyleFlow agentic workflow"
Now we have a safe checkpoint before Claude begins substantial development.
11. Start Claude Code
Open the integrated terminal in VS Code.
Make sure you are inside:
C:\Utvecklingprogram\AI\styleflow-wat
Then start Claude Code using the command provided by your installed Claude Code environment.
Once Claude is working inside the project, it can inspect the project files available to it.
Our first instruction should be deliberately high-level.
Use:
Read PRODUCT.md, WORKFLOW.md and CLAUDE.md.
Do not implement the application yet.
Analyse the StyleFlow Version 1 requirements.
Propose an architecture and implementation plan.
Consider reasonable technology alternatives and explain
your recommended choices.
Identify any important requirements that need clarification.
Do not deploy or publish anything.
This is an important first step.
We don’t immediately say:
Build everything.
First, we see how the agent understands our project.
12. What Should Claude Do?
Claude should inspect:
PRODUCT.md
WORKFLOW.md
CLAUDE.md
Then it might identify requirements such as:
Product catalogue
Categories
Product details
Search
Shopping cart
Checkout
Orders
Admin interface
Database
Tests
Responsive UI
It may then evaluate architecture choices.
For example:
Backend:
Flask
Django
FastAPI
Node.js
Database:
SQLite
PostgreSQL
Frontend:
Server-rendered templates
React
Vue
For a small Version 1 application, Claude might recommend a relatively simple architecture.
For example:
Python
+
Flask
+
SQLAlchemy
+
SQLite for local development
+
Jinja templates
+
CSS
+
Pytest
This is only an example.
The important point is that the agent evaluates the requirements before selecting an implementation.
13. Why Not Tell Claude Which Framework to Use?
We certainly can tell Claude:
Use Flask.
Sometimes that is appropriate.
But our goal in this tutorial is to learn agentic development.
Therefore we deliberately give Claude some decision-making freedom.
Suppose our requirements later change to:
500,000 users
Multiple countries
Separate mobile application
Public REST API
Large development team
Claude might recommend a different architecture.
This demonstrates the difference between:
Follow these exact programming instructions.
and:
Achieve this goal within these constraints.
14. Let Claude Document Its Decision
After reviewing Claude’s proposed architecture, we can approve the plan.
Then ask:
Create docs/decisions.md and record the approved
architecture decisions.
Do not implement the full application yet.
For example, Claude could create:
# StyleFlow Architecture Decisions
## Backend
Selected Flask for Version 1.
Reasons:
- relatively small application
- simple architecture
- fast development
- easy server-rendered interface
- suitable testing ecosystem
## Database
Use SQLite for local Version 1 development.
Keep database access structured so migration to
PostgreSQL remains possible.
## Frontend
Use server-rendered templates with responsive CSS.
A separate SPA frontend is unnecessary for Version 1.
## Testing
Use pytest for automated backend and application tests.
Now our architecture decisions are stored inside the project rather than existing only in a chat conversation.
15. Give Claude Its First Implementation Task
We should still avoid saying:
Build the entire application in one enormous operation.
A better agentic workflow uses manageable goals.
Our first implementation instruction could be:
Follow PRODUCT.md, WORKFLOW.md and CLAUDE.md.
Implement the initial StyleFlow project foundation.
For this step:
1. Create the application structure.
2. Configure the development environment.
3. Create the database foundation.
4. Create the Product and Category models.
5. Add sample development products.
6. Create a basic product-listing page.
7. Add tests for the implemented functionality.
8. Run the tests.
9. Correct implementation problems found by tests.
10. Update README.md.
Do not implement cart, checkout or payments yet.
Do not deploy anything.
When finished, report:
- files created
- decisions made
- tests run
- results
- recommended next step
This is a very different style of prompting from normal AI coding.
We give Claude:
GOAL
+
BOUNDARIES
+
ACCEPTANCE CRITERIA
rather than every line of implementation.
16. Claude Uses Tools
Claude now needs the T in WAT.
Conceptually:
CLAUDE
│
┌─────────────┼─────────────┐
▼ ▼ ▼
Files Terminal Git
│ │ │
▼ ▼ ▼
Read/write Run commands Inspect
source code Run tests changes
The workflow could look like:
Read requirements
↓
Create files
↓
Install/configure dependencies
↓
Create database models
↓
Create product page
↓
Run tests
↓
Observe results
Suppose Claude receives:
8 passed
1 failed
Our workflow tells it not simply to declare success.
Instead:
1 failed
↓
Read test failure
↓
Inspect relevant code
↓
Determine cause
↓
Modify implementation
↓
Run tests again
Eventually:
9 passed
That is our first practical agentic loop.
17. Inspect Claude’s Work in VS Code
AI automation should not mean ignoring the generated code.
After Claude completes the first implementation, inspect the VS Code Explorer.
You may see something similar to:
styleflow-wat/
│
├── app/
│ ├── __init__.py
│ ├── models.py
│ ├── routes.py
│ ├── templates/
│ └── static/
│
├── tests/
│ └── test_products.py
│
├── docs/
│ └── decisions.md
│
├── PRODUCT.md
├── WORKFLOW.md
├── CLAUDE.md
├── README.md
├── requirements.txt
└── .gitignore
The exact structure may be different.
That is expected.
Remember:
We specified the goal and constraints, not the exact file tree.
18. Review Changes with Git
Run:
git status
Then:
git diff
These commands help us see what the agent changed.
This is especially useful in agentic development.
Our workflow becomes:
Claude modifies project
↓
Tests pass
↓
Human reviews
↓
Git diff
↓
Accept?
/ \
Yes No
↓ ↓
Commit Ask Claude
to correct
If everything looks good:
git add .
git commit -m "Add StyleFlow product foundation"
Now we have another safe checkpoint.
19. Human-in-the-Loop
Claude has significant freedom inside our development environment, but not unlimited freedom.
We deliberately defined:
Claude may:
✓ Read code
✓ Create development files
✓ Modify development files
✓ Run local tests
✓ Analyse failures
✓ Fix code
✓ Update documentation
But:
Human approval required:
⚠ Production deployment
⚠ Real payments
⚠ Production database deletion
⚠ Publishing externally
⚠ Sensitive credentials
⚠ High-impact infrastructure changes
This is human-in-the-loop agentic development.
The goal is not:
Give AI control of everything.
The goal is:
Give the agent enough autonomy to perform useful work while maintaining human control over consequential actions.
20. What Have We Built?
At the beginning of this article, we had an empty folder:
styleflow-wat/
We created:
PRODUCT.md
WORKFLOW.md
CLAUDE.md
README.md
.gitignore
We then established:
Business Goal
↓
PRODUCT.md
↓
WORKFLOW.md
↓
CLAUDE.md
↓
Claude Agent
↓
Development Tools
↓
Code
↓
Tests
↓
Feedback
↓
Agent correction
↓
Human review
This is our first practical agentic development environment.
21. The Most Important Difference
With ordinary AI-assisted programming, we might repeatedly ask:
Create the database.
Now create the product page.
Now create the CSS.
Now create the tests.
Fix this error.
With our agentic workflow, we move toward:
Here is the product.
Here is the workflow.
Here are your project rules.
Here are the tools you may use.
Here is the definition of done.
Work toward the goal.
Test your work.
Correct problems.
Stop when human approval is required.
That is a fundamental change in how we work with AI.
The AI is no longer used only as a code generator.
It becomes a controlled development agent.
22. What Comes Next?
We now have:
W = WORKFLOW.md
A = Claude Code
T = Basic development tools
But our agent can become much more capable.
In the next article, we will explore how to give Claude specialized Skills and Tools.
We will look at:
Claude Agent
│
├── UI Design Skill
├── Frontend Skill
├── Backend Skill
├── Database Skill
├── Testing Skill
└── Security Skill
and tools such as:
Files
Terminal
Git
GitHub
Database
APIs
MCP
This will prepare our agent for the larger StyleFlow implementation.
Conclusion
In this tutorial, we moved from the theory of agentic workflows to our first practical development environment.
We created three key documents:
PRODUCT.md
↓
What should be built?
WORKFLOW.md
↓
How should the work progress?
CLAUDE.md
↓
What rules should the agent follow?
We then connected those ideas to Claude Code and VS Code.
Our agent can now:
Understand
↓
Plan
↓
Act
↓
Use tools
↓
Test
↓
Observe
↓
Correct
↓
Report
Most importantly, we remain responsible for the goal, constraints, review and high-impact decisions.
In the next step, we will give our Claude agent more specialized capabilities through Skills, MCP, APIs, databases, Git and other development tools.
→Next Article: Give Claude Skills and Tools: MCP, APIs, Databases and Gi
← Back to AI Automation & Agentic Workflows – Step by Step