> For the complete documentation index, see [llms.txt](https://docs.madrix.dev/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.madrix.dev/hands-on-tutorials/1.-prompt-tips.md).

# 1. Prompt tips

Use this page to write prompts that become **good specifications**.\
Then use the AI Chat to iterate on small changes.

{% hint style="info" %}
Want complete prompts by domain (CRM, ERP, Helpdesk, OKRs)? Also use [Prompt Templates](/hands-on-tutorials/4.-prompt-templates.md).
{% endhint %}

### Principles (what changes the outcome most)

1. **Write testable requirements.** Replace “well done” with objective criteria.
2. **Use lists and enums.** They reduce interpretation and “creativity”.
3. **Say what is not allowed.** Ex: “do not allow status rollback”.
4. **Start small.** Generate the “minimum that works”. Then evolve.
5. **Iterate by block.** Field + validation + UI tweak. One change at a time.

### Recommended format (base prompt)

Copy and adjust. It works well for initial generation.

```
Create a project called: {{PROJECT_NAME}}

Goal: {{DESCRIBE_IN_1_2_LINES}}
UI language: pt-BR.

Profiles (RBAC):
- Admin: full access
- Operator: creates/edits
- Reader: read-only

Modules:
- {{MODULE_1}}
    Entities:
    - {{ENTITY_1}}:
      - {{field}} (required)
      - {{field}} (unique, optional)
      - {{field}} (enum: A | B | C)
      - {{relationship}} (relationship: 1 {{OtherEntity}})
    
    Business rules:
    - {{rule_1}} (if/then)
    - {{rule_2}} (allowed transitions)
    
     Reports:
    - {{report_1}}
    - {{report_1}}

- {{MODULE_2}}
    Entities:
    - {{ENTITY_1}}:
      - {{field}} (required)
      - {{field}} (unique, optional)
      - {{field}} (enum: A | B | C)
      - {{relationship}} (relationship: 1 {{OtherEntity}})
    
    Business rules:
    - {{rule_1}} (if/then)
    - {{rule_2}} (allowed transitions)
    
    Reports:
    - {{report_1}}
    - {{report_1}}


```

### How to reduce ambiguity (with examples)

#### Replace adjectives with rules

* Instead of: “nice and modern screen”
* Write: “theme with primary color #0EA5E9 and secondary #111827”

#### Declare rules “by role”

* “Operator creates and edits only records they created.”
* “Reader cannot create/edit/delete.”
* “Admin can reprocess integrations with errors.”

#### Specify status transitions

* Define the enum.
* Define the allowed transitions.
* Say who can transition.
* Say what happens on transition (log, notifications, etc).

### Checklist before sending the prompt

* [ ] Goal and scope in 1–2 lines.
* [ ] Modules listed.
* [ ] Entities with fields and clear types (enum, date/time, currency).
* [ ] Relationships with cardinality (1, 0..1, N).
* [ ] Business rules in bullets “if/then”.
* [ ] Explicit RBAC (who sees what, who edits what).

{% hint style="warning" %}
Avoid asking for “everything” in a single prompt. If scope grows, split into 3–5 changes.
{% endhint %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.madrix.dev/hands-on-tutorials/1.-prompt-tips.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.