Writing Effective Prompts
The agent is most effective when you give it clear, specific instructions with enough context to understand both what you want and why. Vague prompts produce vague results.
Bad vs. Good Prompts
| Weak Prompt | Stronger Prompt |
|---|---|
| Fix the bug | The login form submits twice when the user double-clicks the submit button. Add debouncing to the onClick handler in src/components/LoginForm.tsx. |
| Add tests | Add unit tests for the calculateDiscount function in src/pricing/discount.ts. Cover the cases: no discount, percentage discount, fixed amount discount, and discount exceeding the total. |
| Refactor this | Extract the validation logic from the UserController into a separate UserValidator class. Keep the same validation rules but make them testable independently. |
| Make it faster | The /api/products endpoint takes 3 seconds to respond. The N+1 query in ProductRepository.findAll() is likely the cause. Add eager loading for the category relationship. |
Structure Your Requests
For complex tasks, structure your prompt with clear sections.
Add a caching layer to the API: Context: We're seeing 500ms response times on the /api/users endpoint due to repeated database queries for the same data. Requirements: - Use Redis for caching (already in our docker-compose) - Cache user profiles for 5 minutes - Invalidate cache on user update/delete - Add cache-hit/miss headers to responses Constraints: - Don't change the existing API response format - Must work with the existing auth middleware
CREOR.md
CREOR.md is a special file at the root of your project that provides persistent instructions to the agent. Think of it as a project constitution -- it is included in every agent interaction, so the agent always knows your project's conventions, architecture, and rules.
What to Include
- Project overview: What the project does, its architecture, and key components.
- Code style: Naming conventions, formatting preferences, import ordering.
- Build commands: How to compile, test, lint, and run the project.
- Testing conventions: Test framework, file naming, mocking patterns.
- Architecture rules: Where different types of code should live, dependency boundaries.
- Common pitfalls: Known issues, workarounds, or things the agent should avoid.
Example CREOR.md
Tip
The .creor/ Directory
The .creor/ directory at your project root holds additional configuration, rules, and agent-generated artifacts. While CREOR.md provides top-level instructions, the .creor/ directory offers more granular control.
Directory Structure
.creor/ rules/ # Additional instruction files (.md) plans/ # Plans generated by the Plan agent skills/ # Custom skill definitions settings.json # Local Creor settings
Rules
The .creor/rules/ directory can contain any number of markdown files with additional instructions. These are loaded alongside CREOR.md and can be used for domain-specific guidelines, team-specific conventions, or temporary rules.
Rules files are automatically discovered and included in the agent's context. You do not need to reference them explicitly -- just create them in the .creor/rules/ directory.
System Prompt Structure
Understanding how the agent's system prompt is assembled helps you write better instructions. The system prompt is built from multiple sources in this order.
| Layer | Source | Purpose |
|---|---|---|
| 1. Base prompt | Built-in | Core agent behavior, tool usage instructions, safety rules. |
| 2. Agent definition | Agent config | Agent-specific instructions (Build, Plan, etc.). |
| 3. Project instructions | CREOR.md | Your project-level instructions and conventions. |
| 4. Rules | .creor/rules/*.md | Additional rules and guidelines. |
| 5. Tool definitions | Tool registry | Available tools with descriptions and parameter schemas. |
| 6. Session context | Conversation history | Previous messages, tool results, and compacted history. |
| 7. User message | Chat input | Your current message with any attachments. |
Your CREOR.md and rules files appear early in the prompt, which gives them high influence over the agent's behavior. Instructions at the project level reliably override default behaviors.
Attachments
You can attach files, images, and URLs to your messages to give the agent additional context.
File Attachments
Drag and drop files into the chat input or use the attachment button. The agent can read the contents of text files, images (for visual analysis), PDFs, and Jupyter notebooks.
Image Attachments
Attach screenshots to show the agent what you see. This is especially useful for UI bugs, design implementation, and visual comparisons. The agent can analyze the image and reference specific elements in its response.
URL Attachments
Paste a URL and the agent will fetch and read the page content. This is useful for referencing documentation, API specs, GitHub issues, or Stack Overflow answers.
Note
Prompting Tips
Be Specific About Location
Reference specific files and functions when you know them. The agent can find things on its own, but pointing it to the right place saves time and avoids ambiguity.
Fix the race condition in useUserProfile hook at src/hooks/useUserProfile.ts -- the cleanup function doesn't cancel the pending fetch.
Provide Error Context
When reporting bugs, include the error message, stack trace, or steps to reproduce. The more the agent knows about the failure, the faster it can diagnose and fix it.
Break Complex Tasks into Steps
For large features, break them into sequential messages rather than one massive prompt. This lets you verify each step before moving on.
Step 1: Create the database schema for the notifications table. [verify, then continue] Step 2: Add the NotificationService with methods for create, markAsRead, and listForUser. [verify, then continue] Step 3: Add the API routes and wire them to the service.
Tell the Agent What Not to Do
Constraints are just as important as requirements. If there are approaches you want to avoid, say so explicitly.
Add form validation to the checkout page. - Don't use any validation libraries -- use native HTML5 validation attributes. - Don't modify the existing submit handler. - Don't change the CSS.
Use Follow-up Messages
The agent maintains full session context. You can refine its work with follow-up messages without repeating yourself.
> (initial) Add a search endpoint to the API. > (follow-up) Add pagination with cursor-based navigation. > (follow-up) Add a rate limit of 100 requests per minute. > (follow-up) Write tests for the edge cases.