Modern (and improved) Handoff with Agentic Setup
Creating a New API Endpoint
Developer Guide and Process Description
1.Introduction
This document describes the standard process for creating a new API endpoint in the data platform. The endpoint can be either a GET or POST operation.
It is important to understand each step in this document and follow the process carefully. Do not skip any sections. Review all requirements and design decisions before any code is written, and ask for clarification if anything is unclear.
2.Overview
An endpoint consists of several parts that must work together. Each part is described below and none of them may be omitted:
- API documentation (schema definition) — the list of endpoints and their schemas for the system, covering parameters, response shapes and error codes. Updated by hand for every release.
- Request handler (request/response logic) — validates the incoming payload, calls the query layer and formats the response returned to the client.
- Query layer (for GET endpoints) — the statement that reads the reporting tables, together with its filters, pagination and cache settings.
- Automated tests — at minimum one success case and one failure case for every endpoint that is added.
- Example request (API collection) — a saved request with sample values, kept with the collection so the rest of the team can reproduce it.
3.General Guidelines
- Follow existing patterns in the codebase. Consistency with the surrounding code is preferred over personal style.
- Reuse common components where possible. Do not copy logic between handlers.
- Keep naming consistent with current conventions. Check a neighbouring endpoint before choosing a name.
- Add appropriate tests. Do not skip this step.
4.Process Steps
The process consists of the following steps, each reviewed before the next begins:
- 1.Gather requirements
- 2.Design the endpoint
- 3.Update schema definition
- 4.Implement handler
- 5.Add query layer (GET only)
- 6.Write tests and examples
---name: create-endpointdescription: Create a new GET or POST endpoint in the platform API.--- ## Interactive Flow ### Common Questions- HTTP method (GET or POST)- Endpoint path (e.g., /reports/summary)- Schema tag (e.g., Reports)- Description (what the endpoint does) ### GET-specific Questions- Table or view to query- Columns to return- Query parameters (e.g., dateFrom, dateTo, filters)- Path parameters (if any)- Cache TTL in seconds (optional) ### POST-specific Questions- Request body schema (input payload)- Entry schema (table to write to)- ReportType enum value (e.g., SALES_SUMMARY)- Period format (e.g., DAILY, WEEKLY, MONTHLY)- File attachment support (yes/no) ## Summary and Confirmation| Item | Details || -------- | ------------------------------------ || Schema | HTTP method, path, tag, description || Handler | Runtime, function name, permissions || Query | Database, table/view, columns || Tests | Success and error scenarios || Examples | Sample request and expected response | ## Code Generation1. Schema path2. Request handler3. Query layer (GET only)4. Tests5. Example request file ## Key Conventions- Ask one question at a time.- Endpoint path starts with '/'.- operationId is camelCase.- Wait for confirmation before generating code.Then
Printed handbook, revised by hand
Now
create-endpoint.md, versioned with the code
Delivering the software is only one part of a good handover. The real test comes later when the client's team starts working on the code on their own. They should be able to make changes without spending their first weeks rediscovering how the project fits together.
This has always been part of how Gangverk defines success. We build products alongside our clients, and ownership shifts over gradually instead of arriving as a hard cutoff at the end of an engagement. The goal is a team that can hit the ground running.
Agentic development has changed that work. A codebase now needs to be clear to the people inheriting it and useful to the agents helping them. On a recent delivery, that idea shaped how we prepared the handoff in today's era of agentic development.
Making the pick up easier for engineers and agents
Most conversations about AI in software focus on speed during development. What matters for handoff is how the system is operated after the build is done. Does the team have the knowledge to react when something breaks? Can new requirements be added without first having to rediscover how everything works?
One way we’ve approached this is by giving engineers and agents enough project context to be useful on their first day. There is an initial file that acts as a map of the repository, pointing to the places an agent should look first so it can find the right context without loading the whole codebase into its memory. Each subsequent link is kept next to the code so it won't drift out of date. Additionally, the agents also get safe access to the live systems it needs to reason about, and the common workflows around them are documented so that anyone can run them correctly.
With this setup, an engineer's first week on an unfamiliar codebase looks different. Instead of reconstructing how everything fits together, they can make changes with the agent guiding them. The repository is already mapped for both people and agents, and that helps the team build, adjust, and ship faster. The examples below show how it works in practice.
Debugging without the tribal knowledge
In a data platform, the most valuable knowledge is operational. When a job failed on last night's run, the time-consuming part was knowing what to inspect, which logs mattered, and what order of events led to the failure. Before the handover, a lot of that knowledge lived in a few people's heads.
We handled this by creating a dedicated MCP role for the agent, an MCP being the standard way to give an agent a safe, defined connection to a system. The role gives read-only access to the live data processing system. The agent can see what ran, when it ran, and what each run logged, without being able to start, stop, or change anything. We then wrote down the team's usual debugging path, including how to find the right processing run among hundreds and how to evaluate the outcomes of it.
Now a new engineer can ask, "Why did last night's financial-data run fail for this entity?" and get an answer that walks through the relevant runs and points to the exact place to look. That kind of operational context which usually takes months to pick up is now available on day one in a matter of seconds.
Extending the system without breaking it
Another challenge is extending the system safely. On a mature system, even a small change usually touches more than it appears to such as authentication, auditing, logging, tracing, testing, etc. Adding new data collection to our data platform meant touching several layers in the right order. Forgetting a step and the feature quietly does nothing (until the developer has scratched the layers by himself).
We turned that path into a guided skill. The agent asks the required questions, shows the files it plans to create or edit, and then works through the layers in the same order every time. The steps that are easy to miss are now part of a routine instead of something someone has to remember.
This can sound like prompt craft but in practice, the useful parts live in the repository. They can be reviewed, versioned, and updated with the code. The skill that explains how to extend the platform gets the same review as the platform code. A team-reviewed prompt is written into the repository so the next engineer inherits it for free. The system gets easier to navigate over time.
The handoff as a head start
The agentic setup is continuously evolving as the descriptions have to keep up with the code. The documentation is kept close to the implementation and thus becomes part of the system rather than a separate document that slowly goes stale. There is always another procedure to capture or a check to automate, implying that a good setup points in a direction more than a complete work. The ways of working that would otherwise leave with the delivery team can now stay in the repository, with the tools and the agents working alongside the engineers every day.
The client inherits a working system that already has documented paths through it. The code explains where to look, the tools carry the usual workflows, and the agents have enough context to help from the first day. As much as we like to deliver working product we also like to bring love to the developers that will maintain it.
As agents become part of development work, handovers need to account for them directly. Clean code and documentation still matter, but so does the shape of the repository with known procedures and agentic knowledge. We will keep sharing the pieces that work in practice.