06-big-tree-and-apis/03-how-to-write-a-script.md

How to write a script

How to write a script

A BigTree script should expose one clear backend capability with a stable input and output shape.

Scripts should be small, explicit, and easy to debug. They should not become a dumping ground for unrelated behavior.

Script design rules

A good script should:

• do one main thing
• accept an explicit object-shaped args
• validate or normalize its inputs
• return a stable result shape
• fail clearly when inputs are invalid or the operation cannot succeed

Keep scripts focused

Examples of focused scripts:

• files_list
• files_save
• db_rpc
• db_list_userids

Avoid generic scripts that try to handle many unrelated operations.

Input shape

Prefer a single object for arguments:

{ clientId, appId, userId, limit }

This keeps the script easier to extend later and easier for LLMs to read.

Output shape

Return a predictable object shape.

Prefer stable shapes such as:

{ ok: true, result: ... }

or a clearly documented domain-specific result.

Avoid returning unrelated shapes for similar cases.

Error behavior

Errors should be clear and actionable.

A caller should be able to understand:

• what failed
• whether the problem is input-related or runtime-related
• what to inspect next

Final rule

A script should represent one well-named backend capability with explicit args, predictable output, and debuggable error behavior.