Nútímaleg (og betri) afhending með agentamiðaðri uppsetningu

, By Gangverk
PLATFORM HANDBOOK
TECHNICAL DOCUMENTATION

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. 1.Gather requirements
  2. 2.Design the endpoint
  3. 3.Update schema definition
  4. 4.Implement handler
  5. 5.Add query layer (GET only)
  6. 6.Write tests and examples
Note:Do not implement anything until the design is reviewed and confirmed. Changes later in the process are more expensive.
Version 1.0Last updated: 14 June 2010Page 1 of 6
Mcreate-endpoint.md
1---
2name: create-endpoint
3description: Create a new GET or POST endpoint in the platform API.
4---
5 
6## Interactive Flow
7 
8### Common Questions
9- HTTP method (GET or POST)
10- Endpoint path (e.g., /reports/summary)
11- Schema tag (e.g., Reports)
12- Description (what the endpoint does)
13 
14### GET-specific Questions
15- Table or view to query
16- Columns to return
17- Query parameters (e.g., dateFrom, dateTo, filters)
18- Path parameters (if any)
19- Cache TTL in seconds (optional)
20 
21### POST-specific Questions
22- Request body schema (input payload)
23- Entry schema (table to write to)
24- ReportType enum value (e.g., SALES_SUMMARY)
25- Period format (e.g., DAILY, WEEKLY, MONTHLY)
26- File attachment support (yes/no)
27 
28## Summary and Confirmation
29| Item | Details |
30| -------- | ------------------------------------ |
31| Schema | HTTP method, path, tag, description |
32| Handler | Runtime, function name, permissions |
33| Query | Database, table/view, columns |
34| Tests | Success and error scenarios |
35| Examples | Sample request and expected response |
36 
37## Code Generation
381. Schema path
392. Request handler
403. Query layer (GET only)
414. Tests
425. Example request file
43 
44## Key Conventions
45- Ask one question at a time.
46- Endpoint path starts with '/'.
47- operationId is camelCase.
48- Wait for confirmation before generating code.

Then

Printed handbook, revised by hand

Now

create-endpoint.md, versioned with the code

Að afhenda hugbúnað er aðeins einn partur af góðri afhendingu. Hin sanna prófraun kemur síðar, þegar teymi viðskiptavinarins fer að vinna sjálft í kóðanum. Það á að geta gert breytingar án þess að eyða fyrstu vikunum í að komast að því hvernig verkefnið hangir saman.
Þetta hefur alltaf verið hluti af því hvernig Gangverk vinnur. Við smíðum vörur í nánu samstarfi við viðskiptavini okkar og eignarhaldið færist smám saman yfir í stað þess að það færist allt yfir í einu í lok samstarfsins. Markmiðið er að teymið geti strax hafist handa.
Agentic-miðuð þróun hefur breytt þessari vinnu. Kóðagrunnurinn þarf nú bæði að vera skýr fyrir fólkið sem tekur við honum og nýtast gervigreindinni sem aðstoðar það. Í nýlegri afhendingu mótaði þessi hugmynd undirbúning okkar að yfirfærslunni á tímum gervigreindar.

Auðveldara að taka við verkefninu, fyrir forritara og agents

Umræðan um gervigreind í hugbúnaðargerð snýst að stóru leyti um hraða í þróun. Við afhendingu skiptir hins vegar máli hvernig kerfið er rekið eftir að smíðinni lýkur. Hefur teymið þekkinguna sem þarf til að bregðast við þegar eitthvað bilar? Er hægt að bæta við nýjum kröfum án þess að þurfa fyrst að rifja upp hvernig allt virkar?
Ein af þeim leiðum sem við höfum farið er að tryggja forriturum og gervigreind nægt samhengi um verkefnið svo þau nýtist frá fyrsta degi. Þar er sérstök upphafsskrá sem virkar sem kort af kóðageymslunn (agents.md)i og vísar á þá staði sem agent ætti að skoða fyrst. Þannig finnur hann rétta samhengið án þess að þurfa að hlaða öllum kóðagrunninum inn í minni. Hver viðbótartilvísun er geymd við hlið kóðans svo hún úreldist ekki. Agents fá einnig öruggan aðgang að kerfum í rekstri sem þeir þurfa að greina og algengustu verkferlarnir í kringum kerfin eru skjalfestir svo hver sem er geti framkvæmt þá rétt.
Með þessari uppsetningu lítur fyrsta vika forritara í ókunnugum kóðagrunni öðruvísi út. Í stað þess að þurfa að púsla saman hvernig allt tengist getur hann gert breytingar með leiðsögn. Kóðageymslan hefur þegar verið kortlögð fyrir bæði fólk og agenta, sem hjálpar teyminu að smíða, aðlaga og gefa út hraðar. Dæmin hér að neðan sýna hvernig þetta virkar í reynd.
Claude – skjalfestir kóða · ChatGPT – notar hæfnipakka (skills) · Copilot – tengist með MCP
Hvaða agent sem teymið notar fær hann sama samhengi: skjölunina í kóðageymslunni, hæfnipakkana sem halda utan um verkferlana og lesaðgang að kerfinu í rekstri í gegnum MCP.

Villuleit án þess að þekkingin sé aðeins í kollinum á fáum

Í gagnakerfi er verðmætasta þekkingin oft rekstrarlegs eðlis. Þegar vinnsla mistókst í næturkeyrslu fór mestur tíminn í að vita hvað ætti að skoða, hvaða loggar skiptu máli og hvaða atburðarás leiddi til bilunarinnar. Fyrir afhendinguna bjó stór hluti þessarar þekkingar í kollinum á örfáum einstaklingum.
Við tókum á þessu með því að búa til sérstakt MCP-hlutverk fyrir agentinn. MCP er stöðluð leið til að veita agent örugga og skilgreinda tengingu við kerfi. Hlutverkið veitir lesaðgang að gagnavinnslukerfinu í rekstri. Agentinn getur séð hvað var keyrt, hvenær það var keyrt og hvað var skráð í logga í hverri keyrslu, án þess að geta ræst, stöðvað eða breytt neinu. Síðan skjalfestum við hefðbundna leið teymisins við villuleit, þar á meðal hvernig finna á rétta vinnslukeyrslu meðal hundruða annarra og hvernig meta á niðurstöðurnar.
Nú getur nýr forritari spurt: „Hvers vegna mistókst næturkeyrsla fjárhagsgagna fyrir þessa einingu?“ og fengið svar þar sem farið er yfir viðeigandi keyrslur og bent á nákvæmlega hvar á að leita. Rekstrarlegt samhengi af þessu tagi, sem tekur yfirleitt marga mánuði að tileinka sér, er nú aðgengilegt á fyrsta degi, á nokkrum sekúndum.

Að víkka út kerfið án þess að brjóta það

Önnur áskorun er að útvíkka kerfið á öruggan hátt. Í þroskuðu kerfi snertir jafnvel lítil breyting oft fleiri hluta en virðist í fyrstu, svo sem auðkenningu, aðgerðaskráningu, loggaskráningu, rakningu og prófanir. Að bæta nýrri gagnasöfnun við gagnakerfið okkar þýddi að snerta nokkur lög í réttri röð. Ef skref gleymist getur eiginleikinn hreinlega verið óvirkur, þar til forritarinn hefur sjálfur grafið sig í gegnum lög kerfisins til að finna út úr því.
Við breyttum þessu ferli í pakka með leiðsögn (skill.md). Agentinn spyr nauðsynlegra spurninga, sýnir hvaða skrár hann hyggst búa til eða breyta og vinnur sig svo í gegnum lögin í sömu röð í hvert skipti. Skrefin sem auðvelt er að gleyma eru nú hluti af föstu verklagi í stað þess að einhver þurfi að muna eftir þeim.
Þetta gæti hljómað eins og vönduð fyrirmælasmíð (prompt craft), en í reynd er gagnlegasta efnið geymt í kóðageymslunni. Þar er hægt að yfirfara það, útgáfustýra og uppfæra samhliða kóðanum. Pakkinn sem útskýrir hvernig á að útvíkka vettvanginn fær sömu yfirferð og kóði vettvangsins. Fyrirmæli sem teymið hefur yfirfarið eru vistuð í kóðageymslunni svo næsti forritari erfir þau án nokkurrar fyrirhafnar. Þannig verður auðveldara að rata um kerfið með tímanum.

Afhending sem forskot

Agent miðaða uppsetningin er í stöðugri þróun, enda þurfa lýsingarnar að haldast í hendur við kóðann. Skjölunin er geymd nálægt útfærslunni og verður þannig hluti af kerfinu í stað þess að vera sérstakt skjal sem úreldist hægt og rólega. Það er alltaf hægt að bæta við verklagi sem þarf að skjalfesta eða athugunum sem má sjálfvirknivæða. Góð uppsetning er því frekar vegvísir en fullklárað verk. Vinnulagið sem annars færi með afhendingarteyminu getur nú orðið eftir í kóðageymslunni, ásamt tólunum og agentunum sem vinna með forriturunum á hverjum degi.
Viðskiptavinurinn tekur við virku kerfi með skjalfestum leiðum til að rata um það. Kóðinn sýnir hvar á að leita, tólin halda utan um hefðbundna verkferla og agentarnir hafa nægt samhengi til að hjálpa frá fyrsta degi. Okkur finnst jafn gaman að afhenda vöru sem virkar og að sýna forriturunum sem munu viðhalda henni smá ást.
Eftir því sem agentar verða hluti af þróunarvinnu þurfa afhendingar að taka mið af þeim. Hreinn kóði og góð skjölun skipta enn máli, en það gerir uppbygging kóðageymslunnar líka, ásamt skýru verklagi og þekkingu sem nýtist agentum. Við munum halda áfram að deila því sem virkar í reynd.