Module 3, Lesson 7: Building Out the Project in YouTrack

In this lesson, I'm taking everything we've built — the specs, the RICE prioritisation, the implementation roadmap — and using Claude Code to populate YouTrack with real, dev-ready issues. Epics, user stories, acceptance criteria, dependencies, the whole thing. By the end, we'll have a proper Agile board ready to hand to a developer (or to your future self in the build module).

ℹ️

The prompt I use in this lesson is shared in the Quick Reference section at the bottom. Don't write it from scratch — copy it, swap in your project ID and phase number, and you're good to go.

Before We Start

Here's what I'd expect you to have under your belt before this lesson:

From previous lessons:

Your implementation roadmap should be written and sitting in your .project folder (Module 3, Lesson 5)
Claude Code should be connected to YouTrack via MCP (Module 3, Lesson 6)
Your YouTrack project should be clean — if you have a demo project left over from testing, delete it before you start

Tools / setup you'll need:

Claude Code running in your WebStorm terminal
YouTrack with your real project open
Your project ID handy (you'll need to drop it into the prompt)

By the end of this lesson, you'll:

Understand how Epics and User Stories relate to each other in YouTrack
Know how to prompt Claude Code to create properly structured issues from your roadmap
Have a fully populated Phase 1 board in YouTrack — Epics, Stories, acceptance criteria, dependencies, and estimates

About This Lesson

Duration: ~20 minutes video + ~30 minutes to run it on your own project
Skill Level: Intermediate
What You'll Build: A populated YouTrack Agile board for Phase 1 of your project, generated entirely by Claude Code from your existing specs and roadmap

This lesson is the payoff for all the planning work we did in Module 2 and the first half of Module 3. All those documents, specs, and roadmap files — they weren't just nice to have. This is where they actually get used.

Watch the Lesson

ℹ️

How I'd suggest going through this: Watch the video first without stopping — just get the big picture. Then come back here and work through the guide section by section. After that, use the prompt in Quick Reference to run it on your own project.

What We're Covering

Here's what I'm walking you through in this lesson and why it matters:

Cleaning up before you start — why I always delete demo issues and start fresh before populating real data
The YouTrack issue prompt — what it contains, why it's structured the way it is, and how to adapt it
How Claude Code asks clarifying questions — and why that's actually a feature, not a bug
Epics vs. User Stories — what they mean in YouTrack, and how this maps to real software engineering practice
What a "done" issue looks like — acceptance criteria, technical deliverables, dependencies, estimates
Running Phase 2 and beyond — same prompt, different phase number; it's that simple

1. Start Clean (~0:00)

The first thing I do before running the real prompt is clean house. If you still have any demo issues from testing the YouTrack MCP connection in the previous lesson, delete them now. Go into YouTrack, find the demo project if you made one, hit the ellipsis, go to settings, and delete it. You want to start with a clean project and zero issues.

Once your project is empty and you've confirmed it — no issues, just the project sitting there — we're ready.

2. The Core Idea

2.1 Epics and User Stories

Before I walk you through the prompt, let me explain the structure we're building toward, because it's borrowed from how software teams have worked for years.

An Epic is a big milestone. Think of it as a chapter heading for a phase of your product. It groups a set of related features under one roof. In YouTrack, it's an issue type of its own — and in our setup, each phase of your implementation roadmap maps to one Epic.

A User Story is the specific thing you want to build within that milestone. Written in this format: "As a [persona], I want to [action] so that [benefit]." It answers: who wants this, what do they want to do, and why does it matter to them. Stories live as sub-issues (subtasks) under their parent Epic.

ℹ️

Think of it like a book outline. The Epic is the chapter. User Stories are the individual scenes inside that chapter. Each scene has its own beginning, middle, and end — but they all add up to the same chapter goal.

This structure isn't just for show. It means when you're in development — whether you're doing it yourself or handing it to someone else — you always know which story belongs to which milestone, what needs to be done first, and what "done" actually means for each piece.

2.2 Why This Connects to Everything We've Already Built

Everything we've done since Module 2 is feeding into this moment. The market research grounded the PRD. The PRD grounded the specs. The specs fed the RICE scoring. The RICE scores built the roadmap. And now the roadmap is becoming a live, actionable board.

When Claude Code reads the specs folder and the implementation roadmap, it's not guessing what to build — it's reading real documents we wrote. That's why the quality of what comes out of YouTrack is good. It's only as good as what went in.

3. Let Me Show You How It Works (~1:30)

3.1 Write Your Prompt in a Scratch File

Here's something I do every time I'm working with a long, complex prompt in Claude Code: I write it in a scratch file first.

In WebStorm, I hit Ctrl+Shift+N to open a new scratch file — just an empty text file sitting outside my project. I paste the prompt there, make my edits (swapping in the right project ID and phase number), then copy the whole thing and paste it into Claude Code.

This way, my prompt is saved. If Claude Code runs out of context and I need to restart, I don't have to re-type anything. I just grab it from the scratch file.

💡

Get into the habit of starting each new chunk of work in Claude Code with clear to free up context. You're not losing anything important — you want Claude Code focused on the current task, not dragging in everything it's ever seen in this session.

3.2 The Prompt

Here's the prompt I use. It's included in full in the Quick Reference section at the bottom — copy it from there.

What it does:

Tells Claude Code to read the specs folder and the implementation roadmap from your .project folder
Specifies your YouTrack project ID and which phase to build out
Defines the exact structure for Epics and User Stories, including the Markdown format for each issue
Tells it to use web search if it needs additional context to fill in the stories properly
Asks it to prioritise based on the feature parity matrix

One thing I added to the version I use: I told Claude Code to ask me clarifying questions before it starts creating issues. That extra line saves me a lot of cleanup. Instead of creating everything and having me fix it after, it checks in first.

3.3 Answering Claude Code's Clarifying Questions

When you paste the prompt and run it, Claude Code will ask you a set of questions before doing anything. This is normal — it's reading your project and verifying assumptions. Here's roughly what it asks and how I answered:

Question 1: Issue types — do you have Epic and User Story types configured?
In my YouTrack setup, I have Epic. I don't have a dedicated "User Story" type, but I do have "Feature." So I told it: use Feature for user stories.

Question 2: Assignee — should issues be assigned?
I said: leave unassigned. You can always assign manually later.

Question 3: Custom fields — should it populate sprint, priority, or dev estimate?
YouTrack has an Estimation field built in. I added that to the project (under custom fields → use existing → Estimation) and told Claude Code: use the Estimation field for dev estimates, ignore other fields.

Question 4: Subtask linking — how should user stories connect to epics?
I said: link user stories as subtasks of their Epic. This is how parent → child works in YouTrack — the Epic is the parent, the Stories are its children.

Question 5: Phase scope — how should stories be grouped within the phase?
I told it to group closely related things together rather than strictly following sprint order. If several stories relate to the same flow (say, all the auth-related ones), they should be near each other. That makes implementation cleaner — you build related things in one push.

Question 6: Tags — should it apply tags?
I said: leave tags for now. I prefer to apply tags manually as the project evolves. You don't need to get this perfect upfront.

Once I had my answers written out in the scratch file, I copied and pasted everything into Claude Code as one block and said "go."

3.4 Let It Run

From here, you can walk away. Claude Code will:

Read your specs and roadmap
Create an Epic for Phase 1
Create all the User Stories as sub-issues under that Epic
Add acceptance criteria, technical deliverables, success metrics, and dependencies to each story
Set estimates where it can figure them out

When it comes back, it'll give you a summary. Don't just glance at it — read it. It'll tell you how many stories were created, what sprint estimates look like, and flag anything it had to make a call on.

⚠️

Claude Code will ask for permission to use tools as it works — hitting your YouTrack MCP, running searches, etc. I use the arrow key to select "Yes, don't ask again" for these because it'll be doing it repeatedly. If you approve them one at a time, it'll pause constantly and take forever.

4. What a Done Issue Looks Like

Once it's finished, head into YouTrack and open one of the stories. Here's what you should see.

The Epic: Has a theme, a scope summary, success criteria for the whole milestone, and a target date. It lists all the child stories. It tells you how many developer days it should take in total.

A User Story: Follows this format:

## User Story
As a [persona], I want to [action] so that [benefit].

## Acceptance Criteria
- [ ] [Testable criterion]
- [ ] [Testable criterion]

## Technical Deliverables
- [Specific implementation item]
- [Specific implementation item]

## Success Metrics
- [Measurable outcome]

## Dependencies
- Blocked by: [PROJ-XXX]
- Blocks: [PROJ-YYY]

## Context
[Additional notes — relevant spec links, edge cases, background]

That's what a properly constructed story looks like. Not just a title. Not just "as a user, I want to log in." A complete brief that a developer — human or AI — can pick up and work from without asking you a dozen follow-up questions.

ℹ️

Notice the stories reference your internal spec files in the Context section. That's intentional. Whoever is building this — you or someone else — can trace every story back to the original spec. Nothing is hanging in the air.

The right-hand panel in YouTrack shows the metadata: issue type (Feature/Epic), priority, assignee, and the Estimation field. Stories also show their dependencies — if one story is blocked by another, that link is live. Click it and it takes you directly to the blocking issue.

5. Running Phases 2 and 3

Once Phase 1 is in there, doing the rest is simple. I don't clear Claude Code's context between phases — I want it to remember what it just did for Phase 1, so the stories are consistent.

I add to the conversation: "Let's now work on scoping out Phase 2." Then I paste the same prompt with Phase 1replaced by Phase 2. That's it.

If you're running low on context (Claude Code will usually tell you), you can clear it and re-run the full original prompt with the new phase number. The prompt has everything it needs to reconstruct the context from your files.

I do the remaining phases off camera in the video — it's the same process, just repeated. You don't need to watch me do it twice.

💡

Nothing here is permanent. If Claude Code creates something that doesn't look right, you can edit issues directly in YouTrack, or come back to Claude Code and say "update issue [ID] to reflect X." This isn't a one-shot process — it's a living board.

6. A Note on What This Is Really For

I want to be honest about the scale of what this produces. When you open the Epic and see thirty-something stories with multi-day estimates, it can feel overwhelming. This takes real work to build. It's not vibing along — if you want software that lasts, it's going to take time.

But the point isn't to scare you. The point is that now you know. You have a realistic picture of the project before you write a single line of code. That's infinitely better than finding out six weeks in that you've built the wrong thing in the wrong order with no way to track what's done and what isn't.

And if you're not doing the build yourself — if you're passing this to a developer or an agency — hand them this YouTrack board. Every story is traceable back to a spec. Every spec is traceable back to research. That's the whole pipeline.

7. You Should Be Able to Build This Now

Here's what you can put together with what we just covered:

A fully populated YouTrack Agile board for any phase of your project, generated from your specs and roadmap
A repeatable process you can run for each phase as you go

Check Yourself

I've deleted any demo issues and started with a clean YouTrack project
I've run the prompt for Phase 1 and have an Epic with User Stories in YouTrack
I can open a story and see acceptance criteria, technical deliverables, and dependencies
I understand the difference between an Epic and a User Story in this context

✅

If you're ticking those boxes, you're ready for the next lesson. The hard planning work is done. The next module is where we actually build it.

If Something's Not Working

⚠️

Claude Code created stories but they're not showing as subtasks of the Epic
What's happening: The subtask link didn't get created, so stories are floating as standalone issues.
How to fix it: Open each story in YouTrack and manually set the parent to the Epic. Or re-run the prompt and explicitly add: "make sure all user stories are linked as subtasks of their parent Epic via the subtask relationship."

⚠️

Claude Code stops and asks me to approve every tool call
What's happening: Default behaviour — it asks before using each MCP tool.
How to fix it: Use your arrow key to select "Yes, don't ask again" the first time it prompts. This applies for the rest of the session.

⚠️

YouTrack issue types don't match what the prompt expects
What's happening: Your YouTrack project might not have "Epic" or "User Story" types configured.
How to fix it: When Claude Code asks its clarifying questions, tell it which types you actually have. In my setup: Epic = Epic, User Story = Feature. Just tell it what to use and it'll adapt.

The Short Version

Here's what I want you to walk away with:

Epics = milestones. One per phase. They group everything in that phase together and give it a target date and success criteria.
User Stories = the individual things to build. Written as "As a [persona], I want to [action] so that [benefit]." They live as subtasks under their Epic.
The prompt does the heavy lifting. You write the specs and roadmap once. Claude Code translates them into YouTrack issues. You just have to answer a few setup questions first.
What you can do now: Start the build module. Your board is ready.

Quick Reference

The Prompt

This is the full prompt used in this lesson. Copy it, replace [YOUR-PROJECT-ID] with your actual YouTrack project ID, and replace Phase [X] with the phase you're building out:

Review the specs in the specs folder and the implementation roadmap.
Using the YouTrack tool (Project ID: "[YOUR-PROJECT-ID]"), create issues for Phase [X].
Follow this structure:

## Epics (one per phase)
- Type: Epic
- Summary: "Phase X: [Phase Name]"
- Description: Include theme, success criteria, and target completion date

## User Stories (subtasks of Epic)
- Type: User Story
- Summary: Clear, action-oriented title (no prefixes like "US-001")
- Description format:

## User Story
As a [persona], I want to [action] so that [benefit].

## Acceptance Criteria
- [ ] [Testable criterion 1]
- [ ] [Testable criterion 2]
- [ ] [Testable criterion 3]

## Technical Deliverables
- [Specific implementation item 1]
- [Specific implementation item 2]

## Success Metrics
- [Measurable outcome]

## Dependencies (Link this inside YouTrack as well)
- Blocked by: [PROJ-XXX] (link to YouTrack issue)
- Blocks: [PROJ-YYY]

## Context
[Additional information a developer needs - relevant spec links, edge cases]

Additionally, when needed, please pull additional context/latest with the web search tool.

Before creating any issues, ask me clarifying questions. Prioritise issues based on the feature parity matrix.

Moving to the Next Phase

Once Phase 1 is done, continue in the same Claude Code session (don't clear unless you're out of context) and say:

Let's now work on scoping out Phase 2.

Then paste the same prompt with Phase [X] updated to Phase 2. Repeat for each phase.

YouTrack Custom Fields to Add

If Claude Code asks about estimation fields and you don't see one, here's how to add it:

In YouTrack, go to your project → Settings → Fields
Click Add field to project
Select Use existing → find Estimation
Save

Now Claude Code can populate dev estimates on each story.

Resources

Links & Docs

YouTrack Agile Boards documentation — useful if you want to customise your board view after populating it
YouTrack Issue Types — reference for understanding Epic, Feature, and other types

Tools Used

YouTrack — free tier available
Claude Code — installed in Module 3, Lesson 3
WebStorm (or VS Code) — terminal host for Claude Code

Questions I Get Asked

Q: Do I have to do all phases at once?

No — and honestly I wouldn't. Do Phase 1, see how the board looks, and adjust your prompt or your answers to the clarifying questions if needed. Once you're happy with how Phase 1 turned out, do Phase 2. The prompt is the same either way.

Q: What if my YouTrack doesn't have Epic as an issue type?

When Claude Code asks its clarifying questions, just tell it what types you have. If you only have "Feature" and "Task," tell it to use Feature for epics and Task for stories. It'll adapt. The naming matters less than the parent → child relationship.

Q: Can I edit the stories after they're created?

Absolutely. YouTrack is just a database at this point. You can edit issue titles, update acceptance criteria, change estimates, add assignees — all of it. Claude Code can also go back and edit issues if you ask it to. Nothing here is carved in stone.

Q: How do I know I'm ready for the next lesson?

If you have an Epic in YouTrack for Phase 1 with User Stories underneath it, and you can open one of those stories and see acceptance criteria and dependencies — you're ready.

💬 Stuck? Come Talk to Us

💡

If something's not clicking or you want to share what you've built — come find us in Discord.
Build What Ships community → https://discord.gg/RFXRf9yg
Drop your question in the right channel. The community's active and I check in there too.

Glossary

Epic: A high-level milestone in YouTrack that groups related user stories together. One Epic per phase of the implementation roadmap. Tracks the theme, scope, success criteria, and target date for that milestone. (first came up in Module 3, Lesson 7)

User Story: A description of a feature from the user's perspective, written as "As a [persona], I want to [action] so that [benefit]." Lives as a subtask under its parent Epic. The smallest unit of work that has a clear definition of done. (first came up in Module 3, Lesson 7)

Acceptance Criteria: The specific, testable conditions that define when a user story is complete. Written as checkboxes so that both a human and an AI can verify against them during development. (first came up in Module 3, Lesson 7)

Subtask: In YouTrack, the parent → child relationship between an Epic and its User Stories. A story is a subtask of its Epic. This is how you navigate between the big milestone and the individual pieces of work. (first came up in Module 3, Lesson 7)

Scratch file: A temporary empty text file you open in your IDE (Ctrl+Shift+N in WebStorm) for writing and saving prompts before pasting them into Claude Code. Not part of your project — just a working notepad. (first came up in Module 3, Lesson 7)