A vague idea can sound clear until an AI coding assistant starts turning it into files.
You may think “build a reading list app” is specific enough. The AI still has to guess whether the app needs accounts, cloud storage, book covers, ratings, editing, filters, mobile support, or an external API.
Every guess can expand the project.
A short project brief prevents many of those assumptions. It explains who the application is for, what problem it solves, which features belong in the first version, which features are intentionally excluded, and how you will decide whether the result works.
The brief does not need to look like a corporate specification. It only needs to be clear enough that you and the AI coding assistant are working toward the same product.
What You Will Learn
By the end of this guide, you should be able to:
- turn a general app idea into a focused project statement;
- describe the target user and primary problem;
- define the main user workflow;
- separate required features from optional ideas;
- record technical constraints before implementation;
- create a simple data model;
- write testable acceptance criteria;
- define what “done” means for the first version;
- prepare a complete brief for the Personal Reading List Tracker.
Why a Project Brief Matters in Vibe Coding
AI coding tools are good at filling gaps.
That strength can also become a problem.
When requirements are missing, the tool may choose:
- a framework you did not request;
- a database you do not need;
- a package for a task the browser can already handle;
- a complicated folder structure;
- an authentication system;
- a different interpretation of the user workflow.
The generated result may still look polished.
That does not mean it matches your intention.
A project brief reduces ambiguity before the first implementation prompt.
It gives you a reference for questions such as:
- Does this feature belong in the first version?
- Did the AI add something outside the agreed scope?
- Does the data structure support the user workflow?
- What behavior should be tested?
- Is the application ready to call complete?
Without a brief, every new idea can feel like part of the current task.
With a brief, new ideas can be recorded for later instead of expanding the first version.
Start with the Problem, Not the Technology
A common beginner mistake is starting with a tool choice.
For example:
Build a React application with a database and an API.
That sentence describes technology, not the user’s problem.
A stronger starting point is:
A reader wants a simple way to save books and track whether they plan to read, are currently reading, or have finished them.
This statement gives the project a purpose.
Technology can be selected after the problem is clear.
For this series, the application can begin with plain HTML, CSS, and JavaScript because the first version does not require a server or database.
The technology choice follows the project needs.
It does not define them.
Define the Target User
A project brief should identify who will use the application.
Avoid descriptions that are too broad.
Weak target user:
Everyone who reads books
Better target user:
An individual reader who wants a simple personal list of books and reading statuses.
The second version is useful because it limits the product.
It suggests that the first release does not need:
- team collaboration;
- public profiles;
- social feeds;
- multiple account roles;
- organization administration.
A focused target user helps prevent unnecessary features.
Target User for This Project
For the Personal Reading List Tracker:
Target user:
An individual reader who wants to keep a small personal list of books in a web browser without creating an account.
This one sentence influences several technical decisions.
Because the user is individual and local:
- no login is required;
- no shared database is required;
- browser storage is acceptable;
- the app can be deployed as a static site.
Write a One-Sentence Product Statement
The product statement should explain what the application does and why it exists.
Use this structure:
A [type of application] that helps [target user] [complete a useful task].
For the reading list project:
A browser-based application that helps an individual reader save books and track their reading status.
This sentence is short enough to remember.
It also gives the AI assistant a stable product direction.
When the tool suggests a social feature or account system, you can compare the suggestion with the statement and reject unnecessary scope.
Define the Main User Workflow
The user workflow describes the sequence of actions that delivers the project’s central value.
For this application:
Enter a book title
→ Optionally enter an author
→ Choose a reading status
→ Add the book
→ View it in the list
Secondary actions include:
Filter the list by status
Remove a book
Refresh the page and keep saved books
A workflow should describe user behavior, not implementation details.
Weak workflow:
Call a JavaScript function, update an array, and write JSON to localStorage.
That may describe part of the code, but it does not explain what the user is trying to accomplish.
The user workflow should remain understandable even if the implementation changes later.
Separate Required Features from Optional Ideas
A project brief should distinguish between:
- required features;
- optional future features;
- intentionally excluded features.
This prevents an AI session from treating every idea as immediate work.
Required Features
For the first version:
1. Add a book title.
2. Add an optional author.
3. Choose a reading status.
4. Display saved books.
5. Filter books by status.
6. Remove a book.
7. Preserve books after a page refresh.
8. Show a useful empty state when no books are saved.
Each feature supports the main workflow.
Optional Future Features
These ideas may be useful later:
- Edit an existing book.
- Sort books by title or date added.
- Search the local list.
- Import book details from an external API.
- Display book cover images.
- Export the list.
They should not be implemented in the first version unless the project plan changes deliberately.
Intentionally Excluded Features
The first version will not include:
- User registration
- Login
- Cloud synchronization
- Social sharing
- Public book reviews
- Personalized recommendations
- Payments
- A custom backend
- A production database
The exclusion list gives you permission to say no.
That is useful when an AI assistant proposes a technically interesting feature that does not belong in the current release.
Record Technical Constraints
Technical constraints guide implementation without turning the brief into a detailed architecture document.
For this project:
- Use plain HTML, CSS, and JavaScript.
- Do not use a frontend framework in the first version.
- Do not add third-party dependencies unless approved.
- Store data in browser localStorage.
- Keep the application deployable as a static website.
- Use semantic HTML where practical.
- Support current desktop and mobile browsers.
- Keep files simple enough for a beginner to review.
These constraints help the AI avoid unnecessary complexity.
For example, without the dependency rule, an assistant may add a library for generating IDs, formatting dates, or managing state.
Those packages may work, but they are not required for this project.
Constraints Should Be Specific but Flexible
Avoid overly rigid instructions such as:
Every function must be exactly ten lines.
That does not improve the product.
Use constraints that support:
- readability;
- reviewability;
- security;
- deployment;
- project scope.
Define a Simple Data Model
A data model describes the information the application needs to store.
For each book:
id
title
author
status
createdAt
A sample object may look like:
{
id: "book-001",
title: "Kindred",
author: "Octavia E. Butler",
status: "want-to-read",
createdAt: "2026-07-11T10:30:00.000Z"
}
Field Definitions
id
A unique value used to identify one book.
title
The required book title.
author
An optional author name.
status
One of a limited set of allowed values.
For example:
want-to-read
reading
finished
createdAt
The date and time when the book was added.
Why the Data Model Matters
Without a defined model, the AI may use different field names in different files.
For example:
bookTitle
title
name
Or:
to-read
wantToRead
want-to-read
Inconsistent field names create bugs and confusion.
A small data model gives the project a shared vocabulary.
Write Acceptance Criteria
Acceptance criteria describe observable behavior that must be true for a feature to be considered complete.
They should be testable.
Weak criterion:
The form should work well.
This is subjective.
Better criteria:
- A book with a non-empty title can be added.
- Leading and trailing spaces are removed from the title.
- A whitespace-only title is rejected.
- The author field may be empty.
- The selected status is displayed with the saved book.
These statements can be tested directly.
Acceptance Criteria for Adding a Book
- The user can enter a title.
- The user can optionally enter an author.
- The user can choose one of the supported statuses.
- A valid book appears in the list after submission.
- A blank or whitespace-only title is rejected.
- The form clears after a successful submission.
- Invalid input does not create a new book.
Acceptance Criteria for Displaying Books
- Every saved book displays its title.
- The author is shown when available.
- The selected status is visible.
- The empty state appears when no books exist.
- The empty state disappears after a book is added.
Acceptance Criteria for Filtering
- The user can view all books.
- The user can filter by Want to Read.
- The user can filter by Reading.
- The user can filter by Finished.
- Filtering does not delete or modify stored books.
Acceptance Criteria for Removing a Book
- Every book has a remove action.
- Removing one book does not remove other books.
- The removed book disappears immediately.
- The removal is preserved after a page refresh.
Acceptance Criteria for Persistence
- Saved books remain after the browser page is refreshed.
- Removed books do not return after refresh.
- The application handles missing saved data without an error.
- Invalid stored data does not permanently break the interface.
The last criterion introduces a useful edge case without requiring a complex recovery system.
Define the First Version’s Pages and Files
This project needs only one page.
A simple file structure could be:
reading-list-tracker/
├── index.html
├── styles.css
├── app.js
├── README.md
└── .gitignore
index.html
Contains the page structure:
- heading;
- book form;
- status filter;
- book list;
- empty state.
styles.css
Contains:
- layout;
- typography;
- form styling;
- list styling;
- responsive behavior;
- visible focus states.
app.js
Contains:
- application state;
- form handling;
- validation;
- rendering;
- filtering;
- removal;
- local storage.
README.md
Explains:
- project purpose;
- local usage;
- features;
- file structure;
- verification steps.
This structure is small enough to understand and large enough to demonstrate a real workflow.
Add Non-Functional Requirements
Functional requirements describe what the application does.
Non-functional requirements describe qualities of the implementation.
For this project:
- The interface should remain usable on narrow mobile screens.
- Form fields should have visible labels.
- Keyboard users should be able to reach interactive controls.
- Text should have sufficient visual contrast.
- The application should not require an internet connection after loading.
- No secret or API key should be required for the first version.
- The code should be readable enough for a beginner to review.
These requirements improve the project without adding large new systems.
They also remind the AI assistant that a working button is not the only measure of quality.
Define What “Done” Means
A project can continue forever unless the first release has a clear stopping point.
The definition of done should include more than “the code exists.”
For this project, version one is done when:
- All required features are implemented.
- Every acceptance criterion has been checked.
- No excluded feature was added.
- The application runs locally without a fatal error.
- Data persists through page refresh.
- The main workflow works on desktop and a narrow mobile viewport.
- Git shows no unexplained files or changes.
- No credentials or private data are committed.
- The README explains how to run and test the project.
- The verified version is committed to Git.
- The application is ready for static deployment.
This list creates a real finish line.
It also gives the AI assistant a set of boundaries when asked to evaluate progress.
Use the Brief as a Review Tool
The project brief is not only for the beginning.
Use it during every development stage.
Before a prompt:
- identify which requirement the task supports;
- select the relevant acceptance criteria;
- define which files may change.
After the AI responds:
- compare the result with the requirement;
- inspect whether excluded features appeared;
- check whether technical constraints were followed;
- test the acceptance criteria.
For example:
Requirement:
Reject blank book titles.
Allowed files:
- app.js
Acceptance criteria:
- Empty string is rejected.
- Whitespace-only input is rejected.
- Valid titles are trimmed and accepted.
Constraints:
- No dependency added.
- No unrelated function renamed.
This is much easier to review than:
Make the form better.
Complete Project Brief: Personal Reading List Tracker
The following brief can be saved as PROJECT_BRIEF.md.
# Personal Reading List Tracker
## Product Statement
A browser-based application that helps an individual reader save books and track their reading status.
## Target User
An individual reader who wants a simple personal book list without creating an account.
## Main Problem
Readers often discover books they want to remember but do not need a large social or cloud-based platform to track them.
## Main Workflow
1. Enter a book title.
2. Optionally enter an author.
3. Select a reading status.
4. Add the book.
5. View it in the list.
6. Filter or remove books later.
## Required Features
- Add a book title.
- Add an optional author.
- Select Want to Read, Reading, or Finished.
- Display saved books.
- Filter books by status.
- Remove a book.
- Preserve the list with localStorage.
- Display an empty state.
## Excluded Features
- User accounts
- Login
- Cloud synchronization
- Social features
- Public reviews
- Payments
- Personalized recommendations
- Custom backend
- Production database
## Technical Constraints
- Plain HTML, CSS, and JavaScript
- No frontend framework
- No third-party dependency without approval
- Browser localStorage for persistence
- Static-site deployment
- Responsive layout
- Semantic HTML where practical
- Beginner-readable code
## Data Model
Each book contains:
- id
- title
- author
- status
- createdAt
Allowed status values:
- want-to-read
- reading
- finished
## Acceptance Criteria
### Add a Book
- Valid titles are accepted.
- Leading and trailing spaces are removed.
- Empty and whitespace-only titles are rejected.
- Author is optional.
- Selected status is saved.
- Form clears after successful submission.
### Display Books
- Every book displays a title.
- Author appears when available.
- Status is visible.
- Empty state appears when the list is empty.
### Filter Books
- All books can be displayed.
- Books can be filtered by each status.
- Filtering does not modify stored data.
### Remove Books
- One selected book can be removed.
- Other books remain unchanged.
- Removal persists after refresh.
### Persistence
- Added books remain after refresh.
- Removed books do not return.
- Missing storage data does not cause an error.
## Definition of Done
- Required features work.
- Acceptance criteria are verified.
- Excluded features are not present.
- No unexplained Git changes remain.
- No secrets are committed.
- README documents setup and testing.
- The verified project is committed.
- The app is ready for static deployment.
This brief is detailed enough to guide implementation without prescribing every function or CSS rule.
Common Project Brief Mistakes
Writing Only a Feature List
A feature list does not explain the user, problem, constraints, or completion criteria.
Include the purpose and workflow.
Including Every Future Idea
A brief should protect the first version from expansion.
Move optional ideas into a separate section.
Using Subjective Requirements
Avoid phrases such as:
Make it beautiful.
Make it modern.
Make it easy.
Replace them with observable requirements where possible.
For example:
The layout remains usable at a 375-pixel-wide viewport.
All form fields have visible labels.
Choosing Technology Before Defining the Problem
Do not add a backend because it sounds professional.
Use only what the current version requires.
Forgetting the Exclusion List
An exclusion list is one of the best defenses against AI-generated scope expansion.
Treating the Brief as Permanent
The brief may change when you discover a real requirement.
Update it deliberately and commit the change.
Do not allow the implementation to drift silently away from the documented plan.
Practical Advice from Software Projects
In real development work, a short clear brief often prevents more problems than a long technical document nobody reads.
The brief should be easy to review before a task.
When working with AI coding tools, I prefer requirements that make the expected change and review boundary obvious.
For example:
Implement the Add Book behavior described in PROJECT_BRIEF.md.
Modify only index.html and app.js.
Do not add dependencies.
Show the proposed plan before editing.
This prompt works because the project brief already defines the product.
The prompt does not need to repeat the entire application description every time.
That is one of the most useful roles of a project brief: it becomes stable context for future AI sessions.
Verify Your Project Brief
Before moving to implementation prompts, confirm that the brief answers:
- Who is the user?
- What problem does the application solve?
- What is the main workflow?
- Which features are required?
- Which features are excluded?
- Which technologies are allowed?
- Which dependencies are prohibited?
- What data does the application store?
- What behavior must be tested?
- What conditions define the first version as complete?
For this series, the Personal Reading List Tracker now has enough structure to begin implementation planning.
Conclusion
A project brief turns a vague idea into a buildable and reviewable plan.
It defines the target user, problem, workflow, required features, exclusions, technical constraints, data model, acceptance criteria, and definition of done.
This structure is especially valuable in vibe coding because AI tools are designed to fill missing details. A clear brief reduces unwanted assumptions and gives you a stable standard for reviewing generated changes.
The Personal Reading List Tracker is now defined well enough to begin working with an AI coding assistant.
The next article will show how to turn this brief into focused prompts that ask for one clear outcome, provide relevant context, set boundaries, and specify how the result should be verified.
Comments
Post a Comment