Do most of the thinking before the coding
The fastest way to waste time with an AI coding tool is to start building an idea that has not been defined. Begin with the “what” and “why,” then turn them into design documents that become the source of truth.
Spend most of your early effort defining the product. Code is easier to change before it exists.
Write one sentence describing the pain point and who experiences it.
Explain what becomes possible when the app works.
Pick observable measures such as signups, completed tasks, or records processed.
Separate must-have flows from features that can wait.
Map the user journey
Use Excalidraw, a simple flowchart, or paper. Show where the user starts, each decision they make, and the outcome they reach.
Break features into smaller flows
“Authentication” becomes sign up, sign in, reset password, log out, and account recovery. Each flow can later become a focused build task.
Write the requirements in Markdown
Plain .md files are easy for humans to maintain, easy for Git to track, and easy for coding agents to read.
Prepare a safe place to build
Your computer needs a repeatable project environment. Ask the AI to guide the setup, but document every command so the project can be recreated later.
Install the required version of Python, Node.js, or another language runtime.
Choose one tool—such as pip, Poetry, npm, or pnpm—and use it consistently.
For Python, run python -m venv venv so one app’s packages do not break another.
List required variables such as DB_URL and API_KEY without writing their secret values into documentation.
.env, API keys, database passwords, and local credentials in .gitignore. If a secret is committed, remove it and rotate it immediately.Give the AI a small set of living documents
Do not force the whole project into one giant prompt. Split the specification by concern so the agent can load only the context needed for the task.
Change the relevant document first
If a feature or architecture decision changes, update its Markdown source before asking the AI to change code.
Ask the agent to sync its context
Tell it which files changed and ask it to summarize the new requirements before implementation.
Keep tasks modular
Build one flow or module at a time. Small tasks are easier to review, test, and undo.
Plan, build, validate, save
Every meaningful change should pass through the same four-stage loop. This makes progress visible and gives you a known-good state to return to.
Read docs/UI_SPEC.md and implement only the account settings form. Preserve existing behavior, add validation tests, run the relevant test suite, and summarize the files changed.
Build with an undo button
Git saves snapshots of the project. GitHub keeps those snapshots off your computer and can turn a finished change into a live deployment.
Start version control
Run git init in the project folder. Commit each working milestone using a clear message such as feat: add login flow or fix: handle expired sessions.
Keep local and remote in sync
Use git pull to retrieve cloud changes and git push to publish your commits to GitHub. Keep main production-ready.
Automate the path to production
Configure GitHub Actions so a push to main runs tests, builds the app, and deploys to Vercel, Railway, AWS, or your selected host.
Push to main → run the test suite → build the package or container → deploy.
Turn repeated instructions into a system
When the same task appears three times, stop re-explaining it. Capture the pattern and make it reusable.
Optionally store session logs in data/conversation_logs.db so your decisions and prompts can be reviewed later.
Look for recurring prompts, boilerplate, and manual configuration steps.
Convert a stable pattern into a script, template, reusable skill, or specialized agent.
Define the style guide, test pattern, inputs, expected output, and review gate.
I want a specialized UI component agent. For every component, follow docs/UI_SPEC.md, include accessible states, add the project’s standard tests, and validate the result before returning it.
Start every app from the same operating document
Copy this into SYSTEM_BLUEPRINT.md, replace the bracketed fields, and keep it current as the architecture changes.
# Project Blueprint: [Insert App Name] ## 1. Executive Summary & Intent - **The Problem:** [One-sentence description of the pain point.] - **The Vision:** [What success looks like when this is live.] - **Success Metrics:** [Signups, tasks completed, data processed, etc.] ## 2. Technical Stack & Environment - **Frontend:** [Next.js, React, Tailwind CSS, etc.] - **Backend:** [Python/FastAPI, Node.js, etc.] - **Database:** [Supabase/PostgreSQL, MongoDB, etc.] - **Hosting:** [Vercel, Railway, AWS, etc.] ### Local Setup Requirements - **Python Version:** [x.x] - **Package Manager:** [pip, Poetry, npm, pnpm] - **Virtual Environment:** `python -m venv venv` - **Required Environment Variables:** [DB_URL, API_KEY, etc.] - **Secret Handling:** Store values in `.env`; keep `.env` in `.gitignore`. ## 3. Modular Requirements Keep detailed specifications as separate living documents: - `docs/UI_SPEC.md`: Components, color palette, states, and layout rules. - `docs/DB_SCHEMA.md`: Tables, relationships, constraints, and data types. - `docs/API_FLOW.md`: Frontend/backend requests and external services. ## 4. Development Loop 1. **Planning:** Update the relevant document before prompting for code. 2. **Execution:** Build one specific module or flow at a time. 3. **Validation:** Run local tests and check for breaking changes. 4. **Versioning:** Commit the known-good state to Git. ## 5. Git & Deployment Strategy - Keep `main` production-ready. - Use conventional commits: `feat: ...`, `fix: ...`, `docs: ...`. - On push to `main`: test → build → deploy to [Hosting Provider]. - Never commit secrets, `.env` files, or private credentials. ## 6. Optimization & Automation - **Memory Hook:** Store session logs in `data/conversation_logs.db`. - Review logs periodically for repeated prompts, boilerplate, and manual setup. - Turn stable patterns into scripts, templates, skills, or specialized agents. ## Working Agreement - The design documents are the source of truth. - Update requirements before implementation. - Build and verify in small, reversible steps. - Human review is required before deployment.
Initialize, seed, prompt, iterate
Initialize
Run git init in your project folder.
Seed
Copy the blueprint above into SYSTEM_BLUEPRINT.md and fill in the bracketed fields.
Prompt
Attach the file and use the opening prompt below.
Iterate
Update the architecture document first, then ask the AI to sync its context and implement the revised requirement.
I am building a new application. I have attached my SYSTEM_BLUEPRINT.md. Read it to understand the architecture, design philosophy, and development workflow. Summarize the key decisions, identify any blocking gaps, and confirm when you are ready to start Phase 2: Scaffolding.