Guides

Writing a good brief

How to describe a plugin so the first build is close to what you meant.

The agent is good at following clear instructions and at filling small gaps sensibly. It cannot read your mind about how your server works. A little precision in the brief saves several rounds of changes.

Describe behavior, not code#

Say what players and admins do, and what should happen. Leave the Java to the agent.

• Commands: names, arguments, who can run them.
• Rules: cooldowns, costs, limits, what blocks an action.
• Feedback: the messages players see, and when.
• Settings: what should be configurable in config.yml and what can stay fixed.
• Permissions: the permission nodes you want, if you use a permissions plugin.

A weak brief and a strong one#

Weak:

Make a home plugin.

Strong:

A /home plugin. Players can set up to 3 named homes with /sethome <name>,
list them with /homes, teleport with /home <name> and delete with
/delhome <name>. Teleports wait 3 seconds and cancel if the player moves
or takes damage. Store homes in a file that survives restarts. Make the
home limit and the delay configurable. Permission: home.use.

The strong version fixes the limit, the cancel rules, persistence and configuration, which are the decisions that otherwise get guessed.

Tell it about your server#

• The engine and version are set in the composer, so you do not need to repeat them.
• Mention other plugins you rely on, such as a permissions or economy plugin, and how you want to integrate. If you want no dependencies, say so.
• Mention constraints, such as "no database" or "keep it to a single class".

Build in small steps#

One concern per run works better than a huge list. Get the core working and building, then add features one at a time. Each run builds on the code from the last.

When you are unsure, plan first#

Switch to Plan mode and describe the idea loosely. The agent asks focused questions, with options to pick from, and writes up an approach. Nothing is changed. When the plan looks right, switch to Build. See Plan and Build modes.

Give it evidence#

If something is broken, show it. Attach the console log or a screenshot and say what you expected. See Attachments.

Review before you trust#

A green build means the code compiles. Read the Files changed diff, especially anything that touches player data, permissions or the economy, and test on a copy of your server first.