From bee-tw-team
Patterns for writing clear, consistent API field descriptions including types, constraints, examples, and edge cases.
npx claudepluginhub luanrodrigues/ia-frmwrk --plugin bee-tw-teamThis skill uses the workspace's default tool permissions.
Field descriptions are the most-read part of API documentation. Users scan for specific fields and need clear, consistent information.
Generates design tokens/docs from CSS/Tailwind/styled-components codebases, audits visual consistency across 10 dimensions, detects AI slop in UI.
Records polished WebM UI demo videos of web apps using Playwright with cursor overlay, natural pacing, and three-phase scripting. Activates for demo, walkthrough, screen recording, or tutorial requests.
Delivers idiomatic Kotlin patterns for null safety, immutability, sealed classes, coroutines, Flows, extensions, DSL builders, and Gradle DSL. Use when writing, reviewing, refactoring, or designing Kotlin code.
Field descriptions are the most-read part of API documentation. Users scan for specific fields and need clear, consistent information.
Every field description answers: What is it? (purpose), What type? (data type), Required? (mandatory), Constraints? (limits/validations), Example? (valid data)
| Field | Type | Required | Description |
|-------|------|----------|-------------|
| id | uuid | — | The unique identifier of the Account |
| name | string | Yes | The display name of the Account (max 255 chars) |
| status | enum | — | Account status: `ACTIVE`, `INACTIVE`, `BLOCKED` |
Note: Use — for response-only fields (not applicable for requests).
For nested objects: status.code, status.description
| Type | Pattern | Example |
|---|---|---|
| UUID | "The unique identifier of the [Entity]" | id: uuid — The unique identifier of the Account |
| String | "[Purpose] (constraints)" | code: string — The asset code (max 10 chars, uppercase, e.g., "BRL") |
| String (format) | "[Purpose] (format example)" | email: string — Email address (e.g., "user@example.com") |
| Enum | "[Purpose]: val1, val2, val3" | type: enum — Asset type: \currency`, `crypto`, `commodity`` |
| Boolean | "If true, [what happens]. Default: [value]" | allowSending: boolean — If \true`, sending permitted. Default: `true`` |
| Integer | "[Purpose] (range)" | scale: integer — Decimal places (0-18) |
| Timestamp | "Timestamp of [event] (UTC)" | createdAt: timestamptz — Timestamp of creation (UTC) |
| Object (jsonb) | "[Purpose] including [fields]" | status: jsonb — Status information including code and description |
| Array | "List of [what it contains]" | operations: array — List of operations in the transaction |
In Requests:
Yes = Must be providedNo = OptionalConditional = Required in specific scenarios (explain in description)In Responses: Use — (response fields are always returned or null)
| Pattern | Format |
|---|---|
| Default values | "Results per page. Default: 10" |
| Nullable fields | "Soft deletion timestamp, or null if not deleted" |
| Deprecated fields | "[Deprecated] Use route instead" |
| Read-only fields | "Read-only. Generated by the system" |
| Relationships | "References an Asset code. Must exist in the Ledger" |
| Don't | Do |
|---|---|
| "The name" | "The display name of the Account" |
| "Status info" | "Account status: ACTIVE, INACTIVE, BLOCKED" |
| "A number" | "Balance version, incremented with each transaction" |
| "The code" | "The asset code (max 10 chars, uppercase)" |
| "The timestamp" | "Timestamp of creation (UTC)" |
Before writing field descriptions:
bee:writing-api-docs for endpoint contextbee:voice-and-tone for consistent styleHARD GATE: CANNOT document fields without verified type information.
| Condition | Decision | Action |
|---|---|---|
| Field types unknown | STOP | Report: "Need schema or type definitions" |
| Constraints not defined | STOP | Report: "Need validation rules for constraints" |
| Required/optional unclear | STOP | Report: "Need field requirement status" |
| Enum values undefined | STOP | Report: "Need complete list of enum values" |
| Default values unknown | STOP | Report: "Need default values for optional fields" |
These requirements are NON-NEGOTIABLE:
| Severity | Criteria | Examples |
|---|---|---|
| CRITICAL | Wrong type, missing required fields | Documents string as integer, skips required field |
| HIGH | Missing constraints, no examples | Max length undocumented, no example values |
| MEDIUM | Vague descriptions, inconsistent format | "The name" instead of "The display name of the Account" |
| LOW | Could be clearer, minor format issues | Description could include more context |
| User Says | Your Response |
|---|---|
| "Field names are self-explanatory" | "Self-explanatory to you ≠ self-explanatory to users. MUST write explicit descriptions." |
| "Just copy the schema" | "Schema lacks context. MUST add purpose, constraints, and examples." |
| "Skip constraints, they're in validation" | "Constraints MUST be documented. Users shouldn't discover limits via errors." |
| "Use placeholder examples (foo, bar)" | "MUST use realistic examples. Placeholders don't demonstrate proper usage." |
| "Required/optional is obvious" | "Nothing is obvious. MUST explicitly mark required vs optional." |
| Rationalization | Why It's WRONG | Required Action |
|---|---|---|
| "Schema documents the type" | Schema doesn't explain purpose or usage | MUST add human description |
| "ID fields don't need description" | Users need to know what ID refers to | Document ALL fields including IDs |
| "Boolean is self-documenting" | Users need to know effect of true/false | MUST explain boolean behavior |
| "Timestamp format is standard" | Which standard? Timezone? Format? | MUST specify format and timezone |
| "Enum values are obvious" | Enum meanings may not be clear | MUST describe each enum value |
| "Same field, same description everywhere" | Context may differ | Tailor description to context |
Signs that field descriptions already meet standards:
If all above are true: Field descriptions are complete, no changes needed.