OpenSpec: razvoj vođen specifikacijama za AI asistente za kodiranje

Ako ste ikad koristili AI asistenta za kodiranje — Claude Code, Cursor, Copilot — poznat vam je obrazac: opišete što želite, AI napiše hrpu koda, a onda otkrijete da je krivo shvatio pola zahtjeva. Kod radi, ali radi pogrešnu stvar. Što je značajka složenija, to je veća vjerojatnost da će se to dogoditi.

OpenSpec je open-source okvir koji između vas i vašeg AI asistenta dodaje sloj pisanog dogovora — prije nego što se napiše ijedan redak koda, vi i AI usuglašavate zahtjeve, scenarije i dizajn, zabilježene u strukturiranim Markdown datotekama koje žive u vašem repozitoriju. Projekt ima više od 62.000 zvjezdica na GitHubu i radi s više od 25 AI alata.

Ovaj članak pokriva kako koristiti OpenSpec, zašto djeluje, kada ga preskočiti, njegova poznata ograničenja i što slijedi.

Kako koristiti OpenSpec uz AI

Instalacija

OpenSpec radi na Node.js 20.19+. Instalirajte ga globalno:

npm install -g @fission-ai/openspec@latest

Zatim ga inicijalizirajte u svom projektu:

cd your-project
openspec init

Naredba init u repozitoriju stvara strukturu direktorija openspec/ i konfigurira integraciju s AI alatima. To je sve — nema API ključeva, nema MCP poslužitelja, nema SaaS računa.

Radni tijek u pet koraka

Osnovni radni tijek OpenSpeca odvija se preko slash naredbi koje upisujete izravno u chat sesiju svog AI asistenta. Naredbe imaju prefiks /opsx:. Evo kako to funkcionira:

/opsx:explore — sesija razmišljanja bez obveza. AI čita vašu bazu koda, odmjerava arhitektonske opcije, crta ASCII dijagrame i nejasnu ideju pretvara u konkretan plan. To je nešto što, među alatima za razvoj vođen specifikacijama, ima jedino OpenSpec, i iznenađujuće je korisno za izbjegavanje samouvjereno pogrešnih putova implementacije.
/opsx:propose <naziv> — AI u jednom potezu izrađuje sve artefakte planiranja: proposal.md (zašto i što), design.md (kako), tasks.md (kontrolni popis implementacije) i delta specifikacije (koji se zahtjevi mijenjaju). Sve to pregledavate i uređujete prije nego se pokrene bilo kakav kod.
/opsx:apply — AI prolazi kroz kontrolni popis zadataka i implementira ih jedan po jedan. Svaki dovršeni zadatak biva označen.
/opsx:sync — spaja promjene delta specifikacija u glavne datoteke specifikacija, bez arhiviranja mape promjene. Korisno kod dugotrajnih promjena ili kad želite zabilježiti djelomičan napredak.
/opsx:archive — dovršava promjenu. Delta specifikacije se uklapaju u kanonske datoteke specifikacija, a mapa promjene seli se u openspec/changes/archive/. Specifikacija kao izvor istine sada je ažurirana za sljedeću promjenu.

Struktura projekta

Tipičan OpenSpec projekt izgleda ovako:

openspec/
├── specs/                 # Izvor istine za ponašanje sustava
│   ├── auth/spec.md
│   ├── payments/spec.md
│   └── ui/spec.md
├── changes/               # Aktivne predložene izmjene
│   └── stripe-integration/
│       ├── proposal.md    # Zašto i što
│       ├── design.md      # Tehnička arhitektura
│       ├── tasks.md       # Kontrolni popis implementacije
│       └── specs/         # Delta specifikacije (što se mijenja)
│           └── payments/spec.md
├── changes/archive/       # Dovršene promjene (revizijski trag)
└── config.yaml            # Opcionalna konfiguracija projekta

Specifikacije koriste jednostavan Markdown format sa zahtjevima (SHALL/MUST/SHOULD) i scenarijima u obliku GIVEN/WHEN/THEN:

# Specifikacija autentifikacije

## Svrha
Upravljanje prijavom korisnika i sesijama.

## Zahtjevi

### Zahtjev: Prijava e-poštom
Sustav SHALL autentificirati korisnike putem e-pošte i lozinke.

#### Scenarij: Ispravne vjerodajnice
- GIVEN registrirani korisnik s e-poštom "user@example.com" i lozinkom "correct-password"
- WHEN korisnik pošalje obrazac za prijavu
- THEN sustav vraća token sesije
- AND korisnik se preusmjerava na nadzornu ploču

Gdje se naredbe pokreću

terminalske naredbe openspec — za init, validate, list, view i config
slash naredbe /opsx: — upisuju se izravno u chat vašeg AI asistenta (Claude Code, Cursor, Codex, Copilot itd.)
nema posebnog interaktivnog načina rada; riječ je samo o chat naredbama u alatu koji već koristite

Zašto ga koristiti

Usklađenost prije koda

Najveći pojedinačni izvor izgubljenog vremena kod AI kodiranja jest neusklađenost. Opisali ste značajku X, a AI je izgradio značajku Y koja izgleda ispravno, ali se ponaša drugačije. Otkrivanje toga nakon 200 redaka koda košta vremena, konteksta, a ponekad i strpljenja.

OpenSpec otkriva neusklađenost već u fazi specifikacije. Pogrešku otkrivenu u proposal.md moguće je ispraviti za pet minuta. Ista pogreška otkrivena tek u pregledu PR-a može trajati satima.

Kontekst koji preživljava sesije

Bez OpenSpeca, kontekst je prolazan. Zatvorite sesiju u Claude Codeu i sve što je AI znao o vašem projektu nestaje. Sljedeća sesija kreće od nule — ista nerazumijevanja, ista potreba za ponovnim objašnjavanjem.

Specifikacije se ubacuju u git. Nova sesija, novi član tima ili tromjesečna pauza na projektu znače čitanje datoteka sa specifikacijama umjesto kopanja po starim chat transkriptima. AI već zna što i zašto.

Pregledavajte namjeru, ne kod

Kod pregleda PR-a s OpenSpecom prvo dolazi delta specifikacija — koji su se zahtjevi promijenili, što je dodano, što uklonjeno. Pregled koda tada samo potvrđuje da implementacija odgovara namjeravanoj promjeni ponašanja. To je brži i informativniji proces pregleda nego buljenje u 500 redaka razlika bez znanja zašto su uopće nastale.

Univerzalan i bez zaključavanja uz dobavljača

OpenSpec radi s Claude Codeom, Cursorom, Codexom, GitHub Copilotom, Windsurfom, Clineom i s više od 25 drugih AI alata. Nema zaključavanja uz jednog dobavljača, nema API ključa koji treba nabaviti, nema ovisnosti o određenom SaaS proizvodu. Ako sljedeći mjesec promijenite AI asistenta, datoteke sa specifikacijama ostaju.

Pročitajte više o tome kada su AI agenti pogrešan izbor u mom postu o okviru za odlučivanje

Kada ga ne koristiti

OpenSpec je iskren o vlastitim ograničenjima — u često postavljanim pitanjima izričito piše: “Ako tražite čarobni alat koji sve planira umjesto vas bez ikakvog truda s vaše strane, ovo to nije.” Evo kada ga je pametno preskočiti:

Trivijalne promjene

Ispravci tipfelera, preimenovanje varijabli i čisto formatiranje ne zahtijevaju cijeli ciklus propose-apply-archive. Ceremonija se ne isplati za promjenu od dva retka. Vodite se zdravim razumom: ako od ljudskog kolege ne biste tražili da napiše specifikaciju za nešto, preskočite OpenSpec i za to.

Čisto vibe kodiranje

Ako brzo prototipirate, istražujete nepoznati API ili namjerno pišete jednokratni kod, proces specifikacija vas usporava umjesto da pomaže. Razvoj vođen specifikacijama zablista kad kod ima dugoročnu vrijednost. Za jednosatne eksperimente jednostavno pišite kod.

Slabi AI modeli

Kvaliteta OpenSpec artefakata ovisi o sposobnosti rasuđivanja AI modela. Jaki modeli (Claude Opus, Codex) proizvode temeljite, logički dosljedne specifikacije. Slabi modeli proizvode nepotpune ili proturječne artefakte koji troše više vremena nego što ga štede. Ako vaš tim iz razloga troškova koristi jeftiniji model, isprobajte OpenSpec na jednoj promjeni prije nego se obvežete na cijeli radni tijek.

Timovi koji ne mogu održavati specifikacije

Zastarjela specifikacija gora je od nikakve. Ako vaš tim isporučuje prebrzo da bi nakon svake implementacijske prilagodbe ažurirao datoteke sa specifikacijama, specifikacija se udaljava od stvarnosti. Kod postaje pravi izvor istine, a specifikacija zavodljiva dokumentacija kojoj novi članovi tima vjeruju bez razmišljanja.

Poznati problemi i ograničenja

Jaz u provjeri

OpenSpec provjerava strukturu datoteka sa specifikacijama — ispravan Markdown format, valjanu sintaksu zahtjeva. Ne provjerava zadovoljava li implementirani kod doista specifikaciju. Ako specifikacija kaže “sustav SHALL odbiti prazne lozinke”, a AI napiše kod koji taj zahtjev zanemaruje, OpenSpec to neće uočiti.

Alati zajednice poput OpenSpec Plus na osnovni OpenSpec dodaju provedbu TDD-a i provjeru po dijelovima, ali osnovni alat taj jaz ostavlja otvorenim.

Nema ugrađenih kontrolnih točaka kvalitete

Zadatke u tasks.md kao dovršene označava sam AI. Ne postoji kontrolna točka koja pita “čekaj, jesi li ovo doista testirao?” ili “zadovoljava li ovo kriterije prihvaćanja?” AI sam izvještava o vlastitom napretku, što poništava svrhu za timove kojima je potrebna provediva kvaliteta.

Upravljanje kontekstnim prozorom

Duge sesije s velikim datotekama specifikacija mogu dosegnuti granice AI konteksta. Vodič za rješavanje problema OpenSpeca to navodi kao poznatu grešku (“context too large”). Rješenje je ručno održavanje higijene konteksta — brisanje povijesti chata prije početka implementacije — što se lako zaboravi.

Arhiviranje stvara dodatan posao u gitu

Svaki korak arhiviranja stvara git promjene na čekanju (spajanje specifikacija) koje treba zasebno commitati. Ako promjenu arhivirate i istovremeno spojite PR s kodom, ažuriranja specifikacija bit će spojena zajedno s promjenama koda. Ako zaboravite sinkronizirati prije spajanja, grana sa specifikacijama nije usklađena s granom koda.

Više od 140 otvorenih problema

Od srpnja 2026. projekt ima otprilike 140 otvorenih problema na GitHubu. Projekt se brzo razvija, no neki rubni slučajevi i zahtjevi za značajkama ostaju neriješeni. Prije nego se za neuobičajen radni tijek oslonite na OpenSpec, provjerite popis prijavljenih problema.

Što slijedi

OpenSpec Workspaces

Tim gradi Workspaces — značajke usmjerene na timove, namijenjene velikim bazama koda, planiranju u više repozitorija i suradnji. Na web stranici stoji: “Sada gradimo za timove.” Prijave za beta verziju su otvorene. Ovo je najkonkretniji sljedeći korak za sam OpenSpec.

OpenSpec Plus

Proširenje zajednice, autora sudokara, dodaje provjeru i kontrolne točke kvalitete koje osnovnom OpenSpecu nedostaju: provedbu TDD-a, implementaciju provjerenu specifikacijom, strukturirano istraživanje i dizajn s više opcija uz analizu kompromisa. Ako vam je provjera glavna briga, vrijedi ga razmotriti.

Širi SDD ekosustav

OpenSpec je najpopularniji alat za razvoj vođen specifikacijama, ali nije jedini. BMAD nudi cjelovit okvir za cijeli životni ciklus, s elicitacijom i korekcijom kursa. Spec-Kit primjenjuje pristup u kojem je specifikacija na prvom mjestu, s “ustavom” na razini projekta. Open Agent Spec, koji razvija Oracle, nije okvir nego deklarativni standard — specifikacije kao verzionirana, pregledna, prenosiva infrastruktura koja nadopunjuje OpenSpec umjesto da mu konkurira.

Trend je jasan: SDD za jednu osobu je zreo. SDD za timove, SDD u više repozitorija i provjereni SDD sljedeće su granice.

OpenSpec popunjava stvarnu prazninu u razvojnom tijeku uz pomoć AI-ja. Nije čarobno rješenje i nije za svaku promjenu, ali za složene značajke kod kojih je usklađenost bitna, štedi više vremena nego što ga troši. Krenite s jednom promjenom, provjerite uklapa li se proces u vaš tim, pa se odatle širite.