← All workshopsAdvanced Workshop
Give your agenta brain
A practical workshop on setting up AI coding agents with the context, rules, and workflows they need to make better decisions.
Why this matters
Most AI coding failures are not model failures. They are context failures.
- The agent does not know what the product is.
- It does not know what good design means for this project.
- It does not know the architecture boundaries.
- It does not know what security rules must never be broken.
- It does not know how you want it to review, debug, or execute work.
- So it guesses.
The .md files reduce guessing. They give the agent a stable set of facts to reason from before it writes a single line of code.
Real examples & templates
What these files look like in practice
The left column is from a live project. The right column is the reusable template. Both are included in the workshop.
CLAUDE.md
Real example
# CLAUDE.md This file defines how Claude should work in this project. ## What this project is ATim Advisory website — static Next.js site. Supporting context files are the source of truth: - product.md — what ATim Advisory is, who it serves - Design.md — brand, typography, colours, UI rules - architecture.md — stack, hosting, project structure - security.md — hard rules around secrets and privacy Do not duplicate these files here. Read them when needed. ## When to read context files Before any meaningful implementation task, read all four. For copy or content changes: read product.md and Design.md For UI, layout, or styling changes: read Design.md and architecture.md For technical structure, routes, or data flow: read architecture.md and security.md For forms, analytics, scripts, or integrations: read security.md — stop and ask before implementing. ## Working principles - Make the smallest useful change - Keep the site static-first - Do not add dependencies unless necessary - Do not refactor unrelated code - Do not invent content, testimonials, or claims ## Performance targets Lighthouse ≥ 95. LCP < 2s. JS < 10KB. ## Development npm run dev # http://localhost:3000 npm run build # generates /out for static hosting ## Where things live Home page copy src/content/advisoryContent.ts Workshop copy src/content/workshopsContent.ts CSS and tokens src/app/globals.css Deployment infra/
Template
# CLAUDE.md This file defines how Claude should work in this project. ## What this project is One paragraph. What it builds. Who it's for. The single most important goal. Supporting context files are the source of truth: - product.md — what the product is and who it serves - Design.md — brand, typography, colours, UI rules - architecture.md — stack and technical boundaries - security.md — hard rules that must never be broken ## When to read context files Before any task, read the relevant files: For copy or content changes: read product.md + Design.md For UI or styling changes: read Design.md + architecture.md For technical or data flow changes: read architecture.md + security.md For forms, auth, analytics, or integrations: stop and explain the tradeoff before implementing ## Working principles - rule the agent must follow every session - rule the agent must follow every session - what the agent must never do - what the agent must never do ## Development how to install and run locally how to build ## Where things live key thing file or folder key thing file or folder
product.md
Real example
# Product context ## What it is ATim Advisory is a senior technology advisory business led by Angela Timofte. It helps founders, CEOs, CTOs, and engineering leaders make better decisions about engineering strategy, AI adoption, and scaling. ## Who it's for Primary: CTOs, CEOs, founders, and VPs of Engineering at scaleups who need senior technology judgment without hiring another full-time executive. Secondary: investors and board members who need an advisor to pressure-test technology strategy. Not for: outsourced development, generic coaching, or someone to simply execute tickets. ## The core problem Leaders sense something is slowing the company down but the root cause is hard to isolate. Engineering is busy but not creating visible business value. AI strategy is vague. Teams scale faster than their operating model. Ownership is unclear. ## What's in scope - Engineering strategy and AI adoption advisory - Organisational design and execution coaching - CTO, founder, and executive advisory - Scaling for growth, acquisition, or IPO ## What's explicitly out of scope - Outsourced software development - Staff augmentation or day-to-day delivery - Generic business coaching ## Success metric A potential client understands whether ATim Advisory is relevant and books an advisory conversation.
Template
# Product context ## What it is One clear paragraph. No jargon. What does it actually do? ## Who it's for Primary: specific person with a specific job and a specific problem they need solved. Secondary: adjacent user who also benefits. Not for: who you are explicitly excluding. ## The core problem What is painful today without this product? Why does the user care enough to change? ## What's in scope - feature or capability - feature or capability - feature or capability ## What's explicitly out of scope - thing you will not build - thing you will not build ## Success metric User can do X within Y minutes or steps.
Design.md
Real example
# Design system ## Brand Product: ATim Advisory Positioning: Senior technology advisory for founders, CTOs, and engineering leaders. Tone: premium, direct, calm Never use: "world-class", "cutting-edge", "bespoke", "revolutionary", "AI-powered everything" ## Colours Primary: #111111 — dark sections, headers Accent: #B08A57 — primary actions, labels Surface: #F7F3EC — page background Text: #1A1A1A — body copy Muted: #6F6A61 — secondary text ## Typography Display: Inter 700 — hero headlines Body: Inter 400 — 16–18px, line-height 1.6 Mono: IBM Plex Mono — labels, metadata, tags ## Layout principles - Strong left alignment throughout - Generous whitespace signals quality - No gradients, no decorative shadows - Cards: clean borders, warm surfaces
Template
# Design system ## Brand Product: your product name Positioning: one sentence, what it is Tone: 3 adjectives that describe the feel Never use: words that feel off-brand or generic ## Colours Primary: #hex — background or strong contrast Accent: #hex — primary action Surface: #hex — cards and panels Text: #hex — body copy Muted: #hex — secondary text ## Typography Display: font name — weight used for headlines Body: font name — size, line-height for body Mono: font name — when and where to use it ## Layout principles - layout rule - layout rule - what to avoid
architecture.md
Real example
# Architecture ## Stack Frontend: Next.js with TypeScript Styling: Global CSS with CSS variables Backend: None — static marketing site Database: None Auth: None — fully public site AI: None — not requested for initial version ## Hosting Frontend: AWS S3 + CloudFront (eu-west-1) API: None Region: eu-west-1 preferred ## What changes frequently - Page copy and advisory areas - CTA text and booking link destination - Workshop content and descriptions ## What must be stable - Static-first architecture (no server required) - Component boundaries and content model - Security rules around no tracking, no forms ## Project structure src/app/ — Next.js App Router pages src/components/ — Shared UI components src/content/ — All editable copy and data infra/ — Deployment scripts
Template
# Architecture ## Stack Frontend: framework + version Styling: CSS approach Backend: runtime + language, or none Database: primary DB, or none Auth: auth provider or none AI: model + API, or none ## Hosting Frontend: where it deploys API: where the backend lives Region: any constraints? ## What changes frequently - thing that will be edited often - thing that will be edited often ## What must be stable - thing that must not change without planning - thing that must not change without planning ## Project structure Brief description of folder layout
security.md
Real example
# Security and privacy rules ## Hard rules — never break these - Never commit secrets, API keys, or .env files - Never add analytics or tracking without approval - Never collect personal data without documentation - Never invent testimonials or client results - Never add packages unnecessary for a static site ## Authentication None. The site is a public marketing page. No routes require auth. No sessions. No tokens. If auth is added: define the architecture first. ## Input handling No forms in v1. CTA is a mailto or booking link. If a form is added later: validate server-side, sanitize all input, add spam protection, document what data is collected and why. ## Dependencies No npm packages beyond Next.js and TypeScript. Any addition must have a clear, justified reason. ## Privacy No cookies. No analytics by default. No profiling. If analytics added: privacy-first provider only, document what is collected, comply with GDPR. ## What to do if unsure Stop. Read security.md. If still unclear, ask before implementing — do not guess.
Template
# Security and privacy rules ## Hard rules — never break these - Never commit secrets or API keys - your non-negotiable rule - your non-negotiable rule - your non-negotiable rule ## Authentication Which routes require auth? What happens if auth fails? Where are tokens stored? ## Input handling What user input reaches your backend? What sanitisation is required? ## Dependencies Your rules for adding new packages. ## Privacy What data is collected? What is never collected? ## What to do if unsure Your rule — ask, comment, or halt?
Reusable prompts
Command files for repeatable agent work
These prompts tell the agent exactly how to approach a task, review code, or debug an issue. Write them once, reuse them on every project.
.claude/commands/task.md
Template
# Task prompt template Before starting, read: - your-context-file.md - your-design-file.md - your-rules-file.md # Task Describe the task in one clear sentence. What exactly needs to change or be built? # Goal What outcome does this create? How will you know it is done? # Scope ## In scope - specific thing to add - specific thing to change ## Out of scope - what not to touch - what not to rebuild # Requirements The implementation must: - follow your rule - follow your rule - avoid your constraint - avoid your constraint
.claude/commands/code-review.md
Template
# Code review prompt Before reviewing, read: - your-context-file.md - your-rules-file.md ## Review priorities 1. security concern 2. correctness concern 3. architecture concern 4. your priority 5. your priority ## Security checklist Check the code does not introduce: - your security rule - your security rule - your security rule ## Output format Critical — must fix before shipping Important — should fix before shipping Minor — fix when convenient
.claude/commands/debug.md
Template
# Debugging prompt Before making changes, read: - your-context-file.md - your-rules-file.md ## Goal Find the root cause. Fix with the smallest safe change. No unrelated refactoring. ## Required steps 1. Understand the problem 2. Find the root cause 3. Make the minimal fix 4. Check for breakage 5. Explain what changed ## Constraints - Do not refactor unrelated code - Do not add dependencies unnecessarily - Do not change behaviour unless required - your constraint
What you will leave with
A reusable setup you can apply to any project
By the end, you will have a reusable project setup that tells your AI agent what it is building, how it should look, what technical boundaries it must respect, what security rules it must never break, and how to execute repeatable tasks.
A project context file
CLAUDE.md that loads the right rules before the agent touches anything.
A product file
product.md that stops the agent from producing output that ignores what the product actually is.
A design file
Design.md that protects taste, consistency, and the decisions that make a product feel considered.
An architecture file
architecture.md that prevents unnecessary complexity and keeps the stack aligned with the plan.
A security file
security.md that encodes the rules your agent must never break, regardless of what else is asked.
Reusable commands
Prompt files for task execution, code review, and debugging that produce consistent, auditable results.
Stop giving your agent isolated prompts.
Give it a system.
This workshop gives you the setup to make AI coding agents more consistent, safer, and more useful on real projects.