The Calm Before Code: Setting Up Your First AI-Powered Project

There's a moment every builder knows. You open a fresh project, fingers hovering over the keyboard, brain buzzing with possibility. And then—chaos. Files everywhere. Errors you don't understand. That sinking feeling of I don't even know where to start.

This article is about preventing that moment entirely.

I'm going to show you the ritual I follow before writing any code. It takes about an hour. It feels slow. And it's the reason my projects don't fall apart two weeks later when I can't remember where anything lives.

No programming experience required. If you can create folders and copy-paste commands, you can do this.

Explain it three ways

👶 Like I'm 5

When we build a blanket fort, we first decide where the blankets and pillows go so it doesn't fall down. This article shows how to lay everything out before we start decorating the fort with lights. That way, when we add the cool stuff later, the whole thing stays standing.

💼 Like you're my boss

This is the operating checklist that keeps AI-assisted projects stable. It covers repo prep, documentation standards, guardrail commands, and deployment configuration—so delivery becomes predictable even with AI in the loop. ROI: one hour of setup prevents 10+ hours of debugging later.

💕 Like you're my girlfriend

You know how we make a plan before rearranging the living room? Same idea. Instead of chasing code glitches later, I spend the first hour mapping folders, writing tiny docs, and running quick checks so the rest of the build feels calm. It's like meal prepping but for software—boring upfront, peaceful later.

The story of two projects

Let me tell you about two versions of me.

Version A opened Cursor, typed "make me a portfolio website," and started building immediately. Three weeks later, I had 47 files in random folders, no idea which version was "the real one," and a production site that crashed because I forgot to set up an environment variable.

Version B spent one hour before touching any code. Made four tiny text files. Ran five commands. Drew a folder map on paper. Then started building.

Version B shipped in half the time with zero mystery errors.

The difference wasn't skill. It was ritual.

What we're building today

By the end of this article, you'll have:

What you'll create	Why it matters
---	---
A folder map that makes sense	So you never lose files or accidentally publish drafts
Four tiny documentation files	So your AI assistant actually understands your project
A "tooling shakedown" habit	So errors get caught before they become disasters
A prompt template that works	So Cursor gives you useful code instead of guesses
A deployment ritual	So your site goes live without mystery failures

Time investment: ~60 minutes

Skill required: Can you create folders and copy-paste? You're qualified.

Step 1: Map your folders (15 minutes)

Before building anything, draw the floor plan.

Create this folder structure in your project:

my-project/
├── docs/                    ← Rules and guides live here
│   ├── FOLDER_MAP.md
│   ├── AI_PRACTICES.md
│   ├── PROMPT_PLAYBOOK.md
│   └── WORK_ORDER_TEMPLATE.md
├── src/                     ← Your actual code
│   ├── app/
│   └── components/
├── content/                 ← Stuff you write
│   ├── drafts/              ← Work in progress (never published)
│   └── published/           ← Ready for the world
└── scripts/                 ← Automation helpers

Why this matters

💡 The "ghost files" story

I once skipped folder mapping and dumped everything into src/. Two weeks later, my AI assistant started suggesting code from a file I'd deleted days ago. Spent three hours chasing "ghost references" before realizing the problem was my messy structure. A 10-minute folder map would have prevented all of it.

The key insight: **drafts stay in content/drafts/ until they're ready.** This way, your published site only references clean, finished content. No accidental "DRAFT - DO NOT PUBLISH" pages going live.

Create your four documentation files

These files are tiny. Each one takes 2-3 minutes to write.

**1. docs/FOLDER_MAP.md**

# Folder Map

- `src/` - All code lives here
- `docs/` - Documentation and rules
- `content/drafts/` - Work in progress
- `content/published/` - Ready for production
- `scripts/` - Automation helpers

**2. docs/AI_PRACTICES.md**

# AI Practices

1. AI is a helpful assistant, not the decision-maker
2. Never paste passwords or secret keys into AI prompts
3. Always review AI suggestions before accepting
4. Security-related code requires human review

**3. docs/PROMPT_PLAYBOOK.md**

# Prompt Playbook

## Good prompt example
"I need a button component that matches our Tailwind config. 
It should have hover states and be keyboard accessible."

## Bad prompt example  
"Make a button" (too vague, AI will guess)

**4. docs/WORK_ORDER_TEMPLATE.md**

# Work Order Template

## Goal
What are we building and why?

## Deliverables
- [ ] Files to create
- [ ] Tests to write
- [ ] Docs to update

## Quality checklist
- [ ] Accessible (keyboard works)
- [ ] Mobile-friendly
- [ ] No lint errors

That's it. Four files, maybe 100 words total. But now your AI assistant has context. It knows where things go. It knows your rules.

Step 2: The tooling shakedown (10 minutes)

Five commands tell you if your project is healthy. Run them every time you start a work session.

Command	What it does	What you want to see
---	---	---
`npm install`	Gets all the pieces your project needs	"added X packages"
`npm run dev`	Starts your local preview	Site loads at localhost:3000
`npm run lint`	Checks for common mistakes	"No problems found"
`npm run type-check`	Catches type errors	"No errors"
`npm test`	Runs your tests	"All tests passed"

How to run these (for complete beginners)

Open your terminal (on Mac: Terminal app. On Windows: PowerShell)
Navigate to your project folder: `cd path/to/my-project`
Type each command and press Enter
Wait for it to finish before running the next one

⚠️ Common oops

Skipping npm run type-check because "the site loads fine." Type errors can hide silently for weeks, then explode when you try to deploy. Run all five commands. Every time.

Log your results

Create a file called DEVLOG.md and add:

## 2025-12-01 — Project Setup

- npm install ✅
- npm run dev ✅ (localhost:3000)
- npm run lint ✅
- npm run type-check ✅
- npm test ✅

Notes: Clean slate, ready to build.

This takes 30 seconds and saves you from wondering "wait, did I run lint?" later.

Step 3: The prompt spine (15 minutes)

This is the secret sauce. A structured prompt template that makes Cursor actually useful.

The template

Context:
- [What project is this? What files matter?]

Observations:
- [Three things you've noticed or constraints you have]

Intention:
- [What are you trying to build, in plain English?]

Quality bars:
- [What standards does this need to meet?]

Format:
- [What do you want back? Code? A plan? Both?]

Ask:
- [Your specific question]

Example: Bad prompt vs. Good prompt

Bad prompt:

"Make me a hero section"

Cursor will guess everything. Colors, layout, content, structure. You'll get something generic.

Good prompt:

Context:
- Building a portfolio site with Next.js and Tailwind
- Using the color palette from tailwind.config.ts

Observations:
- Need a gradient title (purple to cyan)
- Should have a call-to-action button
- Background shouldn't block clicks (pointer-events-none)

Intention:
- Create a hero section that introduces me and links to my work

Quality bars:
- Accessible (keyboard navigation works)
- Mobile-friendly (stacks on small screens)
- Matches existing Tailwind config

Format:
- Create the component file
- Show me what changed

Ask:
- Walk me through your plan before writing code

Cursor will now give you something specific, thoughtful, and aligned with your project.

✨ The magic of "walk me through your plan"

Adding this phrase to your prompts is a game-changer. Instead of Cursor immediately writing code, it explains what it's going to do first. You can catch mistakes before they happen. It's like asking a contractor to describe the renovation before they start knocking down walls.

Step 4: First deployment without drama (20 minutes)

Time to put your project on the internet. We'll use Vercel because it's free and works well with the tools we're using.

The deployment ritual

**1. Create .env.example**

This file lists every setting your project needs, without the actual secret values:

NEXT_PUBLIC_SITE_URL=
NEXT_PUBLIC_GA_ID=

2. Push your code to GitHub

git init
git add .
git commit -m "Initial setup with calm rituals"
git push origin main

3. Connect to Vercel

Go to vercel.com and sign in with GitHub
Click "Import Project"
Select your repository
Add your environment variables (the real values this time)
Click Deploy

4. Verify it works

Wait for the build to complete
Click the preview URL
Make sure your site loads

5. Run a quick health check

Open Chrome DevTools → Lighthouse → Generate Report. Log the scores in your DEVLOG.md.

⚠️ The most common deployment mistake

Forgetting to add .env.local to .gitignore. If you accidentally push secret keys to GitHub, rotate them immediately (create new ones and delete the old). Add this line to your .gitignore file: .env.local

Your completion checklist

Before moving on, make sure you have:

[ ] Folder structure with `docs/`, `src/`, `content/drafts/`, `content/published/`
[ ] Four documentation files created
[ ] All five tooling commands run and logged
[ ] Prompt spine template saved somewhere you can copy-paste it
[ ] `.env.example` created with all required variables
[ ] First deployment live on Vercel
[ ] Lighthouse scores logged in `DEVLOG.md`

What's next?

You've done the hard part—the part most people skip. Your project has structure. Your AI assistant has context. Your deployment pipeline works.

Part 2 shows you how to actually build something: a real component with tests, preview deployments, and documentation. Same calm energy, more visible results.

Ready for the next step?

Learn how to ship features with quality gates—tests, previews, and documentation that actually helps.

Continue to Part 2 →

Interactive lab available

Want to practice these concepts hands-on? The companion lab lets you:

Check off documentation tasks as you complete them
Simulate terminal commands and see expected output
Build your own prompt spine with a guided form
Track your Vercel environment setup

<a href="/learn-ai-lab/vercel-cursor/beginner" className="text-cyan-300 hover:text-cyan-100 underline">→ Try the Beginner Lab</a>

Navigate the series

← Previous

You're at the beginning

Ship It With Confidence

Part 2: Building features with quality gates

The Calm Before Code: Setting Up Your First AI-Powered Project

The Calm Before Code: Setting Up Your First AI-Powered Project

Explain it three ways

The story of two projects

What we're building today

Step 1: Map your folders (15 minutes)

Why this matters

Create your four documentation files

Step 2: The tooling shakedown (10 minutes)

How to run these (for complete beginners)

Log your results

Step 3: The prompt spine (15 minutes)

The template

Example: Bad prompt vs. Good prompt

Step 4: First deployment without drama (20 minutes)

The deployment ritual

Your completion checklist

What's next?

Interactive lab available

Navigate the series

About Frame Architect