Harness Engineering v legacy: agent píše kód

Harness Engineering: Jak agent píše produktový kód v legacy monorepozitáři

V Harness Engineering člověk stanovuje architektonické rámce, testovací scénáře a recenzuje výsledky, zatímco agent generuje veškerý produktový kód. Experiment na legacy monorepozitáři se 310 tisíci řádky Scala/Java ukázal použitelnost přístupu pro běžné úlohy: vyčlenění modulu bez změny chování. Role inženýra se posouvá k řízení kontextu a procesu, agent přebírá mechanickou rutinu.

Monorepozitář: 25 SBT modulů, 8 let historie, vysoce zatížený systém. Úkol — vyčlenit zpracování webhooků kanálu X do samostatné služby podle vzoru existujících adaptérů.

Podmínky experimentu a role účastníků

Člověk nepiše produktový kód. Role jsou přesně rozděleny:

• Člověk: architektonické hranice, rozklad na etapy, požadavky, testy, recenze, finální kontrola.
• Agent: tvorba/úprava kódu, přesun částí, testy podle scénářů, infrastruktura, opravy chyb.

Úkol je typický: mechanický přesun s úpravou propojení, závislostí, bez refaktoringu obchodní logiky. Ověřitelnost prostřednictvím unit a e2e testů.

Příprava kontextu: dokumentace jako rozhraní řízení

Dokumentace se mění v nástroj: ADR popisuje varianty, plán — etapy. Agent pracuje v daných rámcích, bez dohadů.

Příklad ADR:

# ADR-42: Vyčlenit zpracování webhooků kanálu X z monolitu

## Kontext
Kanál X je nyní zpracováván uvnitř jádra. Ostatní kanály běží jako samostatné služby za zprostředkovatelem zpráv.

## Varianty
1. Tenká obálka: přesunout existující kód s minimálními úpravami (balíčky, propojení).
2. Přepsat obsluhu „nově“ na jiném stacku.
3. Nechat jak je.

## Rozhodnutí
Varianta 1: ztrácí se nejméně implicitního chování při přesunu; architektura se srovná s ostatními kanály.

## Důsledky
+ jednotný vzor pro všechny kanály  
− dočasné duplikování kódu; refaktoring — samostatný úkol

Plán po etapách snižuje chyby: od kostry k e2e okruhu.

Etapy a prompty: postupné řízení agenta

Rozdělení na kroky zajišťuje kontrolu. Příklady promptů:

• Architektonický náčrt:

Prostuduj, jak jsou uspořádány adaptéry kanálů A a B: jak se přihlašují k brokeru a publikují příchozí události.
Najdi v monolitu zpracování webhooků kanálu X.
Napiš ADR se třemi variantami: obálka / přepsat / nechat v jádře. Doporuč obálku a popiš důsledky.
Soubory ulož do architecture/adr/, kód zatím neměň.

• Testy jako smlouva:

Ve třídě WebhookHandler je větvení podle typu chatu. Vyneste ho do čisté funkce routeEvent(...).
Chování nezlepšujte — kopírujte větve tak, jak jsou. Napište unit testy: soukromý chat, skupina, neznámý typ, prázdné tělo.
Kritérium: `sbt test` pro modul je zelený.

• Nový modul:

Vytvořte sbt modul channel-x-adapter podle SPEC z ADR-42.
Zkopírujte uvedené soubory z monolitu; měňte jen balíčky, importy a závislosti do úspěšné kompilace bez `dependsOn(core)`.
Zakázáno: v této etapě ne refaktorovat obchodní logiku zpráv.

• E2E okruh:

Přidejte složku e2e/ na pytest + testcontainers: kontejner brokera, PostgreSQL, mock externího API na samostatném portu.
Napište jeden test: POST webhooks s textem "ping" → v brokeru na očekávaném subject se objevila událost s text=ping.

Testy — prostředek řízení: agent se orientuje podle zeleného sbt test nebo pytest.

Výhoda agenta: rutina pod kontrolou

Agent vyniká v:

• Přesunu a úpravě kódu.
• Opakování vzorů podle příkladu.
• Generování boilerplate.
• Budování testovací infrastruktury.
• Řadě stejných úprav.

Příklad e2e testu na pytest + testcontainers:

# fixutury: kontejner brokera, adaptér, mock externího HTTP API

def test_incoming_webhook_publishes_to_broker(e2e):
    e2e.http.post("/webhook/channel-x", json={"message": {"text": "hello", "chat": {"id": 42}}})
    msg = e2e.broker.await_message("inbound.channel-x", timeout_s=5)
    assert msg["text"] == "hello"
    assert msg["chat_id"] == 42

def test_outgoing_command_reaches_external_api(e2e):
    e2e.broker.publish("outbound.channel-x", {"chat_id": "42", "text": "hi"})
    calls = e2e.external_mock.wait_for_requests(method="POST", path_contains="sendMessage")
    assert any(b"hi" in c.body for c in calls)

Kontroluje ne kompilaci, ale chování v propojení: broker, DB, API mock.

Hranice a omezení přístupu

Agent nenahrazuje architektonická rozhodnutí, ale zrychluje mechaniku. Rizika: shodné chyby (zelené testy maskují regrese), nutnost přísných rámců. Použitelné pro legacy s příklady, ne pro greenfield nebo R&D.

Vývojáři mohou dospět k různým závěrům: úspora na rutině vs. overhead na kontext.

Co je důležité

• Harness Engineering — kontrolované prostředí pro agenta: pravidla, nástroje, zpětná vazba.
• Výhoda v přesunu/úpravě kódu a testovací infrastruktuře v legacy projektech.
• Testy — klíčové rozhraní řízení, ne rituál.
• Hranice: typické úlohy s příklady, bez architektonických inovací.
• Průmysl: Anthropic (90 % AI kódu), Meta, Amazon — přechod k AI-native vývoji.

— Editorial Team