How to write a project brief for AI coding tools

A useful project brief for an AI coding tool explains the outcome, who needs it, what the first version must do, and which constraints matter. You do not need to specify every screen or settle every technical choice. You do need to make the important facts visible and separate them from suggestions.

This guide includes a project brief template you can copy and a worked example. It is intended for founders and operators planning a new app, script or automation before implementation begins.

Start with the outcome and the user

“Build a dashboard” describes a screen. “Help a small maintenance team see which requests need attention” describes a purpose. The second statement gives your builder a better basis for discussing scope and choosing an approach.

Write three short sentences:

• Who will use the project?
• What are they trying to accomplish?
• What would a successful first version let them do?

Include the current process if it explains the problem. For example, requests arrive by email, someone copies them into a spreadsheet, and ownership is unclear. Avoid inventing a percentage improvement before you have measured the current process.

Describe one complete journey

A feature list can hide missing steps. Describe the sequence from the user's starting point to a useful result.

For a maintenance request tool, that might be:

1. A staff member records a request and its location.
2. A coordinator assigns it to someone.
3. The assignee updates the status.
4. The coordinator can see unresolved requests.

Explain who can perform each action. “Everyone can view requests” and “only coordinators can assign requests” are different requirements, even if both users see the same dashboard.

For a script, describe its input, the processing it should perform, and the output you expect. For an automation, add the trigger, connected services, and what should happen when an action cannot complete.

Include constraints that could change the foundation

Only include technical details you actually know. Useful constraints include:

• A required platform or an existing service the project must connect to.
• Whether it runs on one computer or needs shared access.
• The kinds of information it handles and who may access them.
• Whether an action sends a message, changes a record, charges money or deletes something.
• Budget, maintenance skills and any genuine launch deadline.
• Known limits, such as unreliable connectivity or an API access requirement.

Use dummy examples instead of passwords, API keys or private customer records. If the project handles sensitive information or has regulatory obligations, identify that early and involve the appropriate specialist before implementation.

You can leave hosting undecided for a local tool. You can leave a payment gateway undecided when the first version does not collect payments. Those choices should follow the project's needs.

Separate facts, preferences and open decisions

An AI-generated recommendation can otherwise look like something you already requested. Give each consequential point a status:

If your notes conflict, keep the conflicting statements visible and ask for clarification. Do not silently replace “staff may edit their own requests” with “staff may edit every request.”

Copy this project brief template

Project name:

Purpose:
Who needs it, and what problem should it solve?

First useful outcome:
What should someone be able to complete in version one?

Main journey:
Describe the steps from starting input to useful result.

Users and access:
Who can see, create, change or approve each item?

Inputs and outputs:
What information comes in, and what should come out?

Constraints:
Required services, environment, budget, sensitive data,
maintenance expectations and known restrictions.

Confirmed requirements:
Preferences to discuss:
Open decisions:
Explicitly outside version one:

First milestone and how to check it:

A plain document is enough. Fill only the sections you understand, and mark missing information as open rather than guessing.

A short example: a maintenance request tool

Here is a fictional starting brief:

We manage a small building. Staff need to report maintenance requests, and one coordinator assigns and tracks them. The first version should record a request, assign it and show whether it is open or complete. Staff should see their own requests; the coordinator should see all requests. Requests contain a location, description and optional photo. Contractor payments, stock management and a public resident portal are outside version one. We prefer a browser interface but need advice on sign-in and hosting.

This is enough to start discussing a foundation. It still needs a decision about access and a practical way to check the first journey. It does not need every notification rule or reporting layout before planning can begin.

Turn the brief into a reviewable plan

Ask your planning tool to summarise what it understood, preserve your explicit requirements and identify decisions that materially affect the approach. Review that summary before implementation. Then turn the first milestone into an observable check, such as recording a request and confirming that only the permitted user can view it.

For the next step, read how to define MVP scope. If you already have a clear plan, use the AI-tool handoff checklist.

Start your project with PenguinKit when you want guidance turning an idea or brief into a reviewable project foundation. The deliverable is a plan and supporting guidance for implementation; your chosen builder still implements and tests the work.