suleymanbyzt Integration Brief
Goal: the person on the other side of the contract should be able to integrate without reading your code or asking you what changed.
Write the brief whenever a task touched an integration surface: REST/GraphQL endpoints, request/response shapes, events, queues, message schemas, shared types, error contracts, auth requirements.
Steps
Identify the audience. Who integrates with this? (mobile app, frontend, another backend team.) Write for them: they know their side, not yours.
Write the brief to
docs/briefs/<slug>.mdusingtemplates/integration-brief.md. It must contain:- What changed and why — two or three sentences.
- The contract, before → after — exact endpoints, methods, field names, types. Mark what is new, changed, and removed.
- A real example — an actual request and response (or event payload), copy-paste ready. Not pseudocode.
- Errors and edge cases — what failure responses look like, what is nullable, what limits apply.
- Migration notes — is the old shape still accepted? Until when? What breaks if they do nothing?
- Open questions — anything the integrating team must decide.
Keep it honest. Everything in the brief is verified against the actual implementation — copy the example from a real call you made, not from memory.
Announce it. In your Done report, include:
Brief: docs/briefs/<slug>.md — hand this to the <mobile/frontend/...> developer.
Do not
- Do not describe your internal implementation. The brief is the contract, not the code tour.
- Do not write "see the code for details". The brief's entire job is that they don't have to.
- Do not skip the brief because the change "is small". A renamed field breaks the other side just as hard as a redesign.