Vibe GuideCheck the environment and initialize
The runtime is software needed to execute the program; dependencies are packages it uses.
Why this milestone?
Install what the project needs and check that a minimal page opens.
Start here1 step · Follow in order
0101Check the runtime and start the projectTo checkOpen this stepClose this step
01What do you need, and what should you keep?
Your technology choices and ordered development tasks.
The URL opens a page and README explains reopening.
Which files should AI read and save in this step?
In your tool’s project chat, ask it to open the files below. If a file is missing, follow the link back to the step that creates it.
Ask AI to read these materials first: docs/design.md · tasks/todo.md
Ask AI to save the result to: README.md · docs/checks.md
Missing these materials? Return to the step that creates them →
02What will this step help you do?
Install what the project needs and check that a minimal page opens.
Understand it, then judge for yourself
What does this concept mean?
The runtime is software needed to execute the program; dependencies are packages it uses.
How would you decide in a different situation?
Does a Git commit prove the runtime works when preview cannot open?
See a reference answer
No. Git tracks files; runtime, dependencies, configuration and startup need separate verification.
Answer in your own words; if unsure, compare the explanation above and check it against your own project.
03What exactly should you do in this step?
OpenClose
The current project chat
Send one action at a time: select and copy its prompt (⌘C on Mac, Ctrl+C on Windows), switch to your tool’s project chat, paste it, replace bracketed fields and send. Wait for the reply and check the stated result before continuing.
Check whether your computer can run this project.OpenClose
Suggested prompt:
Read docs/design.md and tasks/todo.md. Check required software; for anything missing give official installation steps for my system and a success check. Do not build features.
Afterwards, you should see: You know what is missing and where to install it.
Prepare minimal project files before installing packages. An empty folder needs configuration first; inspect and preserve existing files.OpenClose
Suggested prompt:
Read docs/design.md and tasks/todo.md. Inspect existing configuration; if missing, create minimal configuration and startup files for the agreed approach, then install required dependencies. Preserve instructions, rules and existing work. Prepare only a runnable minimal project, without building business features. Explain the first error if setup fails.
Afterwards, you should see: Actual configuration and startup files exist and required packages are installed.
Start the smallest working page and save the startup instructions.OpenClose
Suggested prompt:
Start the minimal project. Give the execution location, actual URL and stop method. Save verified instructions in README.md and results in docs/checks.md.
Afterwards, you should see: The URL opens a page and README explains reopening.
Practice: personal journal (frontend + backend + database)
Use the same learning-journal project throughout this example. For your own project, compare applicable requirements without creating another project.
Send the environment prompt in the project chat. Check Python, create a project .venv for dependencies and install the agreed Flask.
- What should you see after this step?
- A minimal service opens at a real HTTP address; README records directory, start and stop instructions.
- What should you do first if you get stuck?
- For command not found check the runtime; for No module named flask check .venv. Avoid indiscriminate administrator installs.
Match an error to the next action
URL refuses connection
- What should you check first?
- Check that this service is running and compare its actual port.
- Follow these steps to resolve the problem
- Restart only this service and use its current URL, not an old port.
- What should you see after the problem is resolved?
- The current URL opens the minimal page.
Address already in use
- What should you check first?
- Another process occupies the port; this is not a syntax error.
- Follow these steps to resolve the problem
- Identify the owner; if uncertain choose a free project port and update README without terminating unrelated processes.
- What should you see after the problem is resolved?
- Server output and browser use the same new port.
04Not sure how? Follow each action
OpenClose
Check whether your computer can run this project.
- What should you see after this action?
- You know what is missing and where to install it.
- What should you do if that result is missing?
- Copy error text instead of trying many random versions.
Prepare minimal project files before installing packages. An empty folder needs configuration first; inspect and preserve existing files.
- What should you see after this action?
- Actual configuration and startup files exist and required packages are installed.
- What should you do if that result is missing?
- Resolve the specific permission issue rather than deleting configuration.
Start the smallest working page and save the startup instructions.
- What should you see after this action?
- The URL opens a page and README explains reopening.
- What should you do if that result is missing?
- Check the running service and exact URL instead of guessing ports.
05Words in this step
OpenClose
Runtime ↗
The support environment in which code executes.
A recipe needs a functioning kitchen.
Package manager ↗
Installs and manages software packages and dependencies.
Acquire required supplies and track them.
Lockfile ↗
Records resolved dependency versions for repeatable installation.
Record exact part models for the next purchase.
06How should you handle a problem here?
OpenClose
Installation or startup fails
- Where should you look to understand the problem?
- Keep the exact error, working folder and OS version.
- Follow these steps to resolve the problem
- Give AI the error and location. Distinguish missing dependency, version, permission and port issues; fix the identified cause without deleting the project or repeatedly installing tools.
- Expected recovery
- Repeat the original action and obtain the expected result; keep unexecuted checks marked unverified.
Edit the template with actual material, confirm, then copy into the current project conversation. Mark unknowns as undecided and replace examples as needed.
Confirmed · personalized content ready to copy
I am at “Check the runtime and start the project”. Expected: The minimal project starts and README explains reopening; missing prerequisites stay explicit.. Actual screen/error: [add here]. Inspect existing files first. Give one reversible action at a time, its location, and expected result. Do not recreate the project or delete existing work.07Material for this step (fill or copy)
OpenClose
If you completed the individual prompts above, do not resend this full template. Use it to organize this step’s material when needed; replace bracketed fields, confirm and copy into the project chat.
Edit the template with actual material, confirm, then copy into the current project conversation. Mark unknowns as undecided and replace examples as needed.
Confirmed · personalized content ready to copy
First check access to docs/design.md, tasks/todo.md. If missing or inaccessible, identify the prerequisite and owner action, then stop rather than invent prior work.
Read design and tasks/todo.md. Prepare only this project’s runtime and minimal entry. Inspect OS, files, runtime, package manager and lockfile; preserve configuration. Explain missing installation/access with official entry, execution location and verification. Install only agreed dependencies, start the minimal entry, and report actual URL/device/command, logs and stop method. Verify restart and any approved feasibility experiment; record failures as blockers and return to selection. Save actual instructions in README.md and evidence in docs/checks.md; do not build later features or publish.Journal practice: fill or supplement this step
For this full-stack practice only: use this combined prompt, fill its fields and send it once instead of also sending the generic template. It does not authorize later steps.
Edit the template with actual material, confirm, then copy into the current project conversation. Mark unknowns as undecided and replace examples as needed.
Confirmed · personalized content ready to copy
First check access to docs/design.md, tasks/todo.md. If missing or inaccessible, identify the prerequisite and owner action, then stop rather than invent prior work.
Read design and tasks/todo.md. Prepare only this project’s runtime and minimal entry. Inspect OS, files, runtime, package manager and lockfile; preserve configuration. Explain missing installation/access with official entry, execution location and verification. Install only agreed dependencies, start the minimal entry, and report actual URL/device/command, logs and stop method. Verify restart and any approved feasibility experiment; record failures as blockers and return to selection. Save actual instructions in README.md and evidence in docs/checks.md; do not build later features or publish.
I selected the full-stack journal practice.
Check official Python installation and actual version. After verifying commands, use python3 -m venv .venv on Mac/Linux or py -3 -m venv .venv on Windows. Install pinned dependencies using that environment’s Python. Start a minimal Flask entry without journal logic; report actual port and stop method.08Check this before continuing
The minimal project starts and README explains reopening; missing prerequisites stay explicit.
09What should you do if the expected result is missing?
OpenClose
Copy error text instead of trying many random versions.
Compare with an example (illustration, not your result)
Illustrative record: command, directory, versions, real entry, stop method and restart result. Installation is not startup.
Words in this milestoneIn order of appearance; open for the full explanation
More troubleshooting references
Git and environment: troubleshooting
2 situationsThese paths synthesize official docs and public reports, not frequency data. Check the symptom and verify the result.
Git initialization or the first commit fails
Observed symptom: Git reports no repository, unknown identity, or includes unrelated folders.
- What should you check first?
Check project root, git --version, git rev-parse --show-toplevel, and git status.
- Then resolve
Initialize only a new project root. Inspect ancestor repositories first. Ask the owner for commit name/email and configure this repository only. Review ignored and staged files before committing.
- Verify the result
The root is correct and git log -1 shows the intended commit without secrets or unrelated files.
Edit the template with actual material, confirm, then copy into the current project conversation. Mark unknowns as undecided and replace examples as needed.
Confirmed · personalized content ready to copy
I am blocked at: Git initialization or the first commit fails.
Project and tool: [name, version, and project path]
Observed behavior: [steps, exact error, or screenshot; remove secrets and personal data]
Expected result: [actual goal]
First inspect: Check project root, git --version, git rev-parse --show-toplevel, and git status.
Proposed approach: Initialize only a new project root. Inspect ancestor repositories first. Ask the owner for commit name/email and configure this repository only. Review ignored and staged files before committing.
Explain the evidence and cause before making the smallest relevant fix. Preserve existing changes and do not add features. If I must act, give one precise action at a time and its expected visible result.
Success criteria: The root is correct and git log -1 shows the intended commit without secrets or unrelated files.
Report actual checks, unchecked items, and the next step.ReferencesGit · git init ↗GitHub · Commit username ↗GitHub · Commit email ↗
Dependencies fail or preview refuses to open
Observed symptom: A command is missing, installation fails, or the browser refuses a connection.
- What should you check first?
Read README, version files, lockfile, the first terminal error, and current directory.
- Then resolve
Use the required runtime and matching package manager; do not mix lockfiles. Run the defined start command, keep it running, and open its actual URL and port. Inspect logs and listening address if needed.
- Verify the result
The actual URL loads and the terminal has no startup failure; record commands and versions.
Edit the template with actual material, confirm, then copy into the current project conversation. Mark unknowns as undecided and replace examples as needed.
Confirmed · personalized content ready to copy
I am blocked at: Dependencies fail or preview refuses to open.
Project and tool: [name, version, and project path]
Observed behavior: [steps, exact error, or screenshot; remove secrets and personal data]
Expected result: [actual goal]
First inspect: Read README, version files, lockfile, the first terminal error, and current directory.
Proposed approach: Use the required runtime and matching package manager; do not mix lockfiles. Run the defined start command, keep it running, and open its actual URL and port. Inspect logs and listening address if needed.
Explain the evidence and cause before making the smallest relevant fix. Preserve existing changes and do not add features. If I must act, give one precise action at a time and its expected visible result.
Success criteria: The actual URL loads and the terminal has no startup failure; record commands and versions.
Report actual checks, unchecked items, and the next step.Referencesnpm · Install Node.js and npm ↗Astro · Develop and build ↗Vite · Original connection-refused report ↗
References for this milestone
Open these when the question arises; they are not extra required actions.
- How can technology be chosen without jargon?
After scope and key interactions are clear.
- How can AI stay on task?
When sending a new task, requesting an edit or reporting an error.
My project material and backups
Material stays in this browser, not in project files or AI chat. Chinese and English template drafts are separate; project selection and progress are shared. Do not enter passwords or API keys here.
Includes idea, progress, template drafts, personal checks and selection conditions, but not project code. Restore creates a new draft and preserves existing projects.
Download/import unavailable? Restore backup text
Draft and progress stay in this browser.
Complete the actions in order; expand the matching checks and remedies if you get stuck.