A coding assistant cannot see the application you imagine unless you describe the parts that matter.
A prompt such as “build the reading list app” may produce a working-looking result, but the AI still has to guess which files to create, which technologies to use, how books should be stored, what counts as valid input, and whether it is allowed to add packages.
Those guesses create unnecessary risk.
A stronger prompt does not need to be extremely long. It needs to give the AI a clear goal, the relevant project context, practical constraints, expected output, and a way to verify the result.
This article shows how to turn the Personal Reading List Tracker project brief into focused AI coding tasks.
What You Will Learn
By the end of this guide, you should be able to:
- identify why vague coding prompts produce inconsistent results;
- write a prompt with a clear goal;
- provide only the project context relevant to the task;
- define which files may and may not change;
- describe expected behavior with acceptance criteria;
- ask the AI to plan before editing;
- request a useful change summary;
- add verification instructions;
- separate one large request into smaller implementation tasks;
- create reusable prompt templates for GitHub Copilot and Claude Code.
A Good Prompt Is a Small Task Specification
A coding prompt is not only a question.
It is a compact task specification.
It should tell the AI:
- what needs to change;
- why the change is needed;
- where the change belongs;
- what must remain unchanged;
- how success will be checked.
A useful structure is:
Goal
Context
Constraints
Expected behavior
Files in scope
Verification
Output format
Not every prompt needs every section written as a formal heading. The important point is that the information is present.
For example:
Goal:
Add validation to the book form.
Context:
This is a plain HTML, CSS, and JavaScript reading list app. Books are stored in an in-memory array for now.
Constraints:
Do not add dependencies. Do not modify styles.css.
Expected behavior:
Trim the title. Reject empty and whitespace-only titles. Author remains optional.
Files in scope:
index.html and app.js
Verification:
Explain how to test valid, empty, and whitespace-only titles.
Output:
Show a short plan before making changes.
This gives the AI a much smaller decision space than:
Improve the form.
Start with One Clear Goal
Every implementation prompt should have one main goal.
Weak prompt:
Build the reading list app and make it responsive, add local storage, filters, editing, and a book API.
This request contains several independent tasks:
- page structure;
- styling;
- persistence;
- filtering;
- editing;
- external API integration.
If the AI changes many files, reviewing the result becomes difficult.
A focused prompt might be:
Create the initial HTML structure for the Personal Reading List Tracker. Include a page heading, a form with title, optional author, and reading status fields, an Add Book button, an empty-state message, and a container for the book list.
That task has one clear outcome: the initial page structure.
The next task can add styling. Another can add JavaScript behavior.
Small prompts create small diffs.
Small diffs are easier to understand, test, and commit.
Provide Relevant Context
The AI needs enough context to understand the task, but not every fact about the project.
Relevant context may include:
- the application purpose;
- the current technology;
- the existing file structure;
- the current stage of implementation;
- the data model;
- project rules;
- related functions or components.
For the reading list project:
This project is a browser-based Personal Reading List Tracker built with plain HTML, CSS, and JavaScript. It does not use a framework or third-party dependencies. The first version stores data locally and does not require user accounts.
That paragraph helps prevent the AI from introducing React, a backend, or an authentication system.
Include the Current Project State
Tell the AI what already exists.
For example:
The project currently contains index.html, styles.css, app.js, README.md, and PROJECT_BRIEF.md. The HTML form already exists, but app.js does not yet handle form submission.
Without this information, the AI may recreate existing files or assume the project is empty.
Do Not Paste Unrelated Context
Too much context can also reduce quality.
Avoid including:
- unrelated files;
- old error logs;
- several abandoned implementation ideas;
- full documentation that does not affect the current task;
- private credentials;
- confidential code.
Provide the smallest amount of context that allows the AI to make the correct decision.
State the Constraints Explicitly
Constraints tell the AI what it must not do.
Useful constraints include:
- Use plain JavaScript.
- Do not add dependencies.
- Do not rename existing files.
- Do not modify unrelated functions.
- Do not create a backend.
- Do not change the data model.
- Keep the implementation beginner-readable.
Without constraints, the AI may select a technically valid but inappropriate solution.
For example, a request to generate unique book IDs might lead the AI to install a package.
For this project, a browser-provided API or a small internal function may be sufficient.
A useful prompt would say:
Generate a unique ID without adding a third-party package.
File Boundaries Are Especially Useful
Tell the AI which files are allowed to change.
For example:
Modify only app.js. Do not change index.html, styles.css, README.md, or PROJECT_BRIEF.md.
This does not guarantee the tool will obey perfectly, but it creates a clear review boundary.
After the task, run:
git status
If another file changed, investigate it.
Describe Expected Behavior
A request such as “add validation” leaves many questions.
What input is valid?
What happens when validation fails?
Should the form clear?
Should an error appear?
Should the application change existing data?
Expected behavior answers those questions.
For the reading list form:
Expected behavior:
- Trim leading and trailing spaces from the title.
- Reject an empty or whitespace-only title.
- Allow an empty author.
- Preserve the selected reading status.
- Add one book when the input is valid.
- Do not change the list when the input is invalid.
- Clear the title and author fields after successful submission.
These statements are close to acceptance criteria.
They also give you a test checklist after implementation.
Tell the AI How to Verify the Change
A coding assistant should not only generate code. It should help verify the result.
Add instructions such as:
After making the change:
1. Summarize the files modified.
2. Explain how the input validation works.
3. List manual test cases.
4. Do not make any additional changes.
For a project with automated tests:
Run the existing test command and report the result. Do not install a new test framework.
For a simple browser project:
Provide manual verification steps for a valid title, an empty title, a whitespace-only title, and an empty author.
Verification instructions reduce the chance that the AI treats code generation as the end of the task.
Ask for a Plan Before Editing
For a task that may affect several files, ask the AI to inspect and plan first.
Example:
Read PROJECT_BRIEF.md and inspect the current project. Do not change any files yet. Identify the smallest set of files needed to implement the Add Book feature, then provide a short implementation plan.
Review the plan before allowing edits.
Check whether the AI proposes:
- files that actually exist;
- an unnecessary framework;
- a new package;
- changes outside the requirement;
- a different data model;
- an overly complex architecture.
If the plan is too broad, correct it before code is generated.
For example:
Do not add a state-management library. Keep the implementation in app.js and use the existing form in index.html.
Planning first is especially valuable with project-level coding agents.
Ask for Clarification When Requirements Conflict
A good coding assistant should not guess silently when important requirements conflict.
You can include:
If the current code conflicts with PROJECT_BRIEF.md, stop and explain the conflict before editing.
Or:
If you need to change a file outside the allowed list, ask for approval first.
This creates a decision point.
For example, the AI may discover that the status values in index.html are:
to-read
in-progress
done
while the project brief defines:
want-to-read
reading
finished
The tool should not choose one set without mentioning the conflict.
You need to decide which definition becomes the project standard.
Compare Weak and Improved Prompts
Example 1: Creating the Initial Page
Weak prompt:
Create a reading list app.
Problems:
- no technology choice;
- no scope;
- no file limit;
- no required fields;
- no verification;
- no exclusion rules.
Improved prompt:
Read PROJECT_BRIEF.md and create the initial HTML structure for the Personal Reading List Tracker.
Use the existing index.html file.
Include:
- A page heading
- A form with a required book title
- An optional author field
- A status selector with want-to-read, reading, and finished
- An Add Book button
- A filter control
- An empty-state message
- A container for the book list
Constraints:
- Use semantic HTML where practical.
- Do not add JavaScript behavior yet.
- Do not add dependencies.
- Do not modify styles.css or app.js.
- Keep labels visible and associate them with their inputs.
Before editing, show a short plan. After editing, summarize the structure added.
This prompt produces a result that is easier to review.
Example 2: Adding Form Behavior
Weak prompt:
Make the form work.
Improved prompt:
Implement the Add Book form behavior in app.js.
Project context:
- Plain HTML, CSS, and JavaScript
- No dependencies
- The form and list container already exist in index.html
- Books use the fields id, title, author, status, and createdAt
Expected behavior:
- Prevent the default form submission.
- Trim the title and author.
- Reject an empty or whitespace-only title.
- Allow an empty author.
- Use the selected status.
- Add one book object to the in-memory books array.
- Render the updated list.
- Clear the title and author fields after success.
- Do not clear the form when validation fails.
Constraints:
- Modify only app.js.
- Do not add localStorage yet.
- Do not add editing or filtering.
- Do not add dependencies.
Verification:
- Explain how to test valid input, empty input, whitespace-only input, and an empty author.
Show a short plan before editing.
The improved prompt defines the task boundary clearly.
Example 3: Adding Local Storage
Weak prompt:
Save the books.
Improved prompt:
Add browser localStorage persistence to the existing reading list.
Requirements:
- Load saved books when the app starts.
- Save the full books array after a book is added.
- Save the updated array after a book is removed.
- Use one clearly named storage key.
- Treat missing storage as an empty list.
- If stored JSON is invalid, recover with an empty list and log a concise warning.
Constraints:
- Modify only app.js.
- Do not change the data model.
- Do not add dependencies.
- Do not add cloud storage or a backend.
- Do not change the form or CSS.
After implementation:
- Summarize the new functions.
- List the storage key used.
- Provide manual tests for adding, refreshing, removing, and invalid stored JSON.
The prompt identifies the normal behavior and an important failure case.
Use Acceptance Criteria as Prompt Input
The project brief already contains acceptance criteria.
Do not rewrite them from memory.
Select the criteria relevant to the current task and include them in the prompt.
For example:
Implement book removal according to these acceptance criteria:
- Every displayed book has a remove action.
- Removing one book does not affect other books.
- The selected book disappears immediately.
- The removal remains after page refresh.
This keeps implementation aligned with the documented plan.
It also creates a direct relationship between:
Requirement
→ Prompt
→ Code change
→ Test
→ Commit
Avoid Asking the AI to “Improve Everything”
Open-ended improvement prompts can create wide, subjective changes.
Examples to avoid:
Make the code cleaner.
Improve the design.
Refactor the whole app.
Make it production-ready.
Fix all issues.
These phrases do not define completion.
A more focused request might be:
Review app.js for duplicated rendering logic. Identify duplication first without changing files. If duplication exists, propose one small refactor that preserves behavior and does not change the public data model.
Or:
Improve keyboard accessibility for the Add Book form only. Do not redesign the page or change the color palette.
The narrower request is easier to review.
Keep Prompts Separate from Conversations That Have Drifted
Long AI sessions can accumulate outdated assumptions.
The assistant may remember:
- an earlier file structure;
- a feature you later removed;
- an abandoned framework;
- an incorrect status value;
- a temporary workaround.
When the conversation becomes confused, start a fresh task with:
- the current project state;
- the relevant project brief section;
- the exact goal;
- the current error or requirement;
- file boundaries.
Do not depend on dozens of earlier messages to preserve critical instructions.
A fresh, focused prompt can be more reliable than another corrective message in a drifting session.
Use Different Prompt Styles for Copilot and Claude Code
The core prompt structure remains the same, but the emphasis may differ.
GitHub Copilot Prompt Style
Copilot is often useful for focused editor tasks.
Example:
In app.js, update validateBookTitle so it trims the input and returns false for non-string or whitespace-only values. Do not modify other functions. Explain the edge cases after suggesting the change.
This works well when the relevant file and function are already open.
Claude Code Prompt Style
Claude Code can inspect a wider project context.
Example:
Read PROJECT_BRIEF.md and inspect the existing Add Book implementation. Do not edit yet. Identify which files participate in form submission and rendering. Then propose the smallest plan to add title validation without changing the data model or adding dependencies.
After approving the plan:
Proceed with the plan. Modify only the files identified as necessary. Run the existing verification steps, then summarize every changed file.
The Claude Code prompt emphasizes repository inspection and change scope.
Create a Reusable Prompt Template
You can use the following template for future implementation tasks.
Task:
[Describe one clear outcome.]
Project context:
[Describe the relevant technology, current state, and project rules.]
Relevant requirements:
[List the acceptance criteria that apply.]
Files allowed to change:
- [File name]
- [File name]
Files that must not change:
- [File name]
- [File name]
Constraints:
- [No dependencies]
- [No framework change]
- [No unrelated refactoring]
- [Preserve the current data model]
Verification:
- [Manual test or command]
- [Edge case]
- [Existing behavior that must remain]
Process:
1. Inspect the relevant files.
2. Show a short plan before editing.
3. Ask before expanding the scope.
4. Make the smallest change that satisfies the task.
5. Summarize every modified file.
6. Do not make additional changes after the summary.
This template is intentionally practical rather than decorative.
Remove sections that do not apply to a small task.
Example Prompt for the First Implementation Step
The next article will begin building the application one feature at a time.
A suitable first implementation prompt is:
Task:
Create the initial page structure for the Personal Reading List Tracker.
Project context:
- Read PROJECT_BRIEF.md before planning.
- The app uses plain HTML, CSS, and JavaScript.
- There is no framework, backend, or third-party dependency.
- This task covers structure only, not JavaScript behavior.
Requirements:
- Add a clear page heading.
- Add a form with a required title field.
- Add an optional author field.
- Add a reading-status selector with want-to-read, reading, and finished.
- Add an Add Book button.
- Add a filter control.
- Add a book-list container.
- Add an empty-state message.
Files allowed to change:
- index.html
Files that must not change:
- styles.css
- app.js
- PROJECT_BRIEF.md
- README.md
Constraints:
- Use semantic HTML where practical.
- Use visible labels associated with form controls.
- Do not use inline JavaScript.
- Do not add external libraries.
- Do not create extra pages.
Verification:
- Confirm that every required control exists.
- Confirm that labels are connected to inputs.
- Confirm that status values match PROJECT_BRIEF.md.
Process:
1. Inspect index.html and PROJECT_BRIEF.md.
2. Show a short plan before editing.
3. Make only the requested structural changes.
4. Summarize the final HTML sections.
This prompt provides enough detail for implementation without telling the AI exactly how every HTML line must look.
Review the Prompt Before Sending It
Before submitting a coding prompt, ask:
- Does it contain one main goal?
- Does it explain the relevant project context?
- Are the expected behaviors testable?
- Are file boundaries clear?
- Are prohibited changes listed?
- Does it prevent unnecessary dependencies?
- Does it specify how the result will be verified?
- Does it ask for a plan when the task is broad?
- Is any private or sensitive information included?
- Can the result become one focused Git commit?
If the prompt fails several of these checks, revise it.
Practical Advice from AI-Assisted Development
The best prompt is not necessarily the longest prompt.
Long prompts can still be vague, contradictory, or overloaded.
The most useful prompts create a narrow decision boundary.
When I work with AI coding tools, I want the task to produce a change that can be reviewed as one coherent unit. That means the prompt should be closely related to the intended Git commit.
For example:
Prompt goal:
Add title validation.
Expected commit:
Validate book titles before adding them.
This alignment makes the workflow easier to manage.
A prompt that produces five unrelated changes will also produce a weak commit boundary.
Thinking about the future diff and commit before sending the prompt is one of the most practical ways to improve AI-assisted development.
Common Prompting Mistakes
Giving Only the Desired Feature
“Add filtering” does not define status values, user behavior, file scope, or verification.
Including Too Many Features
Large prompts create large changes and make failures harder to isolate.
Omitting Constraints
The AI may add a package, framework, or backend that the project does not need.
Asking for Code Before Inspection
For multi-file tasks, the AI may begin with an incorrect assumption about the project.
Accepting the First Plan Automatically
Review whether the plan is proportional to the task.
Using Subjective Language
Phrases such as “make it beautiful” or “make it professional” do not provide testable criteria.
Forgetting Edge Cases
Normal input is only one part of the behavior.
Include empty, invalid, duplicate, or missing data when relevant.
Asking the AI to Verify Its Own Work Without Evidence
Request actual test steps, command output, or observable behavior.
The AI’s statement that “everything works” is not enough.
Verify Your Prompting Approach
Before continuing, you should be able to turn this:
Add books to the app.
into something closer to:
Implement Add Book form submission in app.js.
Use the existing form in index.html and the book data model in PROJECT_BRIEF.md.
Requirements:
- Trim title and author.
- Reject empty or whitespace-only titles.
- Allow an empty author.
- Save id, title, author, status, and createdAt.
- Render the new book immediately.
- Clear title and author after success.
Constraints:
- Modify only app.js.
- Do not add localStorage yet.
- Do not add dependencies.
- Do not change filtering or removal.
Show a short plan before editing and provide manual verification steps afterward.
The second prompt produces a clearer implementation and a more reviewable Git diff.
Conclusion
Effective AI coding prompts are focused task specifications.
They define one goal, provide relevant context, set clear constraints, describe expected behavior, identify file boundaries, and explain how the result should be verified.
The purpose is not to control every line of generated code. It is to reduce unnecessary assumptions and create changes that are small enough to understand.
For the Personal Reading List Tracker, prompts should remain connected to the project brief and acceptance criteria.
The next article will use these prompting principles to break the application into small implementation steps. We will examine why building one feature at a time creates better AI responses, clearer Git history, and easier debugging.
Comments
Post a Comment