Spec ya open-source ya uratibu wa Codex: Symphony
Na Alex Kotliarskyi, Victor Zhu, na Zach Brock
Miezi sita iliyopita, tulipokuwa tukifanyia kazi zana ya ndani ya kuongeza tija, timu yetu ilifanya uamuzi uliokuwa wa utata (wakati huo): tungejenga repo yetu bila kanuni yoyote iliyoandikwa na binadamu. Kila mstari katika uhifadhi wa mradi wetu ulipaswa kuzalishwa na Codex.
Ili hilo lifanye kazi, tulibuni upya workflow yetu ya uhandisi kutoka chini kwenda juu. Tulijenga uhifadhi unaofaa mawakala, tukawekeza sana katika majaribio ya kiotomatiki na guardrails, na tukamchukulia Codex kama mshiriki kamili wa timu. Tuliandika safari hiyo katika chapisho letu la awali la blogu kuhusu harness engineering.
Na ilifanya kazi, lakini kisha tukakutana na kikwazo kilichofuata: kubadili muktadha.
Ili kutatua tatizo hili jipya, tulijenga mfumo unaoitwa Symphony. Symphony(fungua katika dirisha jipya) ni orkestra ya wakala inayobadilisha ubao wa usimamizi wa miradi kama Linear kuwa control plane ya mawakala wa uandishi wa kanuni. Kila kazi iliyo wazi hupata wakala, mawakala huendesha mfululizo, na binadamu hupitia matokeo.
Chapisho hili linaeleza jinsi tulivyounda Symphony—jambo lililosababisha ongezeko la 500% la PR zilizounganishwa katika baadhi ya timu—na jinsi ya kuitumia kubadilisha kifuatiliaji chako cha issue kuwa orkestra ya wakala inayowashwa kila wakati.
Kikomo cha mawakala wa uandishi wa kanuni wa mwingiliano
Hata kadri wanavyokuwa rahisi kutumia, mawakala wa uandishi wa kanuni—iwe kupitia programu za wavuti au CLI—bado ni zana za mwingiliano.
Kadri kiwango cha kazi za kiwakala kilivyoongezeka OpenAI, tuligundua aina mpya ya mzigo. Kila mhandisi angefungua vipindi vichache vya Codex, akagawa kazi, akapitia matokeo, akaelekeza wakala, kisha akarudia. Kwa vitendo, watu wengi waliweza kusimamia kwa urahisi vipindi vitatu hadi vitano kwa wakati mmoja kabla kubadili muktadha hakujawa chungu. Zaidi ya hapo, tija ilishuka. Tungeisahau ni kipindi kipi kilikuwa kinafanya nini, kuruka kati ya terminal ili kuwarudisha mawakala kwenye mkondo, na kutatua hitilafu za kazi za muda mrefu zilizokwama katikati.
Mawakala walikuwa wa haraka, lakini tulikuwa na kikwazo cha mfumo: umakini wa binadamu. Kwa hakika tulikuwa tumejenga timu ya wahandisi wa junior wenye uwezo mkubwa sana, kisha tukawapa wahandisi wetu wa kibinadamu kazi ya kuwasimamia kwa karibu. Hilo halingeweza kukua kwa kiwango hicho.
Mabadiliko ya mtazamo
Tulitambua kwamba tulikuwa tukiboresha jambo lisilo sahihi. Tulikuwa tukiupanga mfumo wetu kuzunguka vipindi vya uandishi wa kanuni na PR zilizounganishwa, ilhali PR na vipindi ni njia tu za kufikia lengo. Workflows za programu kwa kiasi kikubwa hupangwa kulingana na vitu vinavyopaswa kukabidhiwa: issues, kazi, tiketi, milestones.
Kwa hiyo tukajiuliza nini kingetokea kama tungeacha kuwasimamia mawakala moja kwa moja na badala yake kuwaacha wavute kazi kutoka kwenye kifuatiliaji chetu cha kazi.
Wazo hilo likawa Symphony, spec iliyoandikwa inayofanya kazi kama msimamizi wa kuoratibu kazi za kiwakala.
Kubadilisha kifuatiliaji chetu cha issue kuwa orkestra ya wakala
Symphony ilianza na dhana rahisi: kazi yoyote iliyo wazi inapaswa kuokotwa na kukamilishwa na wakala. Badala ya kusimamia vipindi vya Codex katika tabo nyingi, tuliifanya issue tracker yetu kuwa control plane.
Katika mpangilio huu, kila issue iliyo wazi ya Linear inalingana na eneokazi maalum la wakala. Symphony huendelea kufuatilia ubao wa kazi na kuhakikisha kwamba kila kazi inayotumika ina wakala anayeendelea katika mzunguko hadi ikamilike. Wakala akianguka au kukwama, Symphony humwanzisha upya. Kazi mpya ikitokea, Symphony huiokota na kuanza kuipangia kazi.
Tulijenga workflow yetu kwa msingi wa hali za tiketi, tukitumia kidhibiti kazi cha Linear kama state machine.
Kwa vitendo, Symphony hutenganisha kazi na vipindi na pia na maombi ya mabadiliko ya kanuni. Baadhi ya issue huzalisha PR nyingi katika repo tofauti; nyingine ni uchunguzi au uchambuzi mtupu ambao haugusi kabisa codebase.
Kazi inapofanywa kuwa ya kufikirika kwa njia hii, tiketi zinaweza kuwakilisha vipande vikubwa zaidi vya kazi.
Tunatumia Symphony mara kwa mara kuoratibu vipengele changamano na uhamishaji wa miundombinu. Kwa mfano, tunaweza kufungua kazi inayomtaka wakala kuchanganua codebase, Slack, au Notion na kutoa mpango wa utekelezaji. Tukisharidhika na mpango huo, wakala huzalisha mti wa kazi, akigawa kazi katika hatua na kufafanua utegemezi kati ya kazi.
Mawakala huanza tu kufanyia kazi zile kazi zisizozuiwa, kwa hivyo utekelezaji hujitokeza kwa njia ya asili na bora sambamba kwa DAG hii (mfuatano wa hatua za utekelezaji). Katika mfano ulio hapa chini, tuliweka uboreshaji wa React kuwa umezuiwa hadi uhamishaji kwenda Vite ukamilike. Kama ilivyotarajiwa, mawakala walianza kuboresha React tu baada ya uhamishaji kwenda Vite kukamilika.
Mawakala wanaweza pia kujitengenezea kazi wenyewe. Wakati wa utekelezaji au ukaguzi, mara nyingi huona maboresho yaliyo nje ya upeo wa kazi ya sasa: tatizo la utendaji, fursa ya kufanyia refactor, au usanifu bora zaidi. Hilo likitokea, wanafungua issue mpya tu ambayo tunaweza kuitathmini na kuipangia baadaye—nyingi za kazi hizi za ufuatiliaji pia huokotwa na mawakala. Ingawa tunasimamia mchakato huu, mawakala hubaki wamepangwa vizuri na kuendeleza kazi mbele.
Namna hii ya kufanya kazi hupunguza sana gharama ya kiakili ya kuanzisha kazi zenye ukungu. Wakala akipata jambo vibaya, hiyo bado ni taarifa yenye manufaa, na gharama kwetu huwa karibu sifuri. Tunaweza kwa gharama ndogo sana kufungua tiketi kwa wakala aende kutengeneza prototype na kuchunguza, kisha kutupa uchunguzi wowote tusiozipenda.
Kwa sababu orkestra inaendeshwa kwenye devbox na hailali kamwe, tunaweza kuongeza kazi kutoka popote na kujua wakala ataichukua. Kwa mfano, mhandisi mmoja kwenye timu yetu alifanya mabadiliko matatu muhimu kutoka programu ya Linear kwenye simu yake akiwa katika kibanda tulivu chenye wifi duni.
Ongezeko la uchunguzi kutokana na kufanya kazi kwa njia hii
Tulipotazama athari za kufanya kazi na Symphony, mabadiliko yaliyo wazi zaidi yalikuwa matokeo. Miongoni mwa baadhi ya timu OpenAI, tuliona idadi ya PR zilizounganishwa ikiongezeka mara 6 katika wiki tatu za kwanza. Nje ya OpenAI, mwanzilishi wa Linear Karri Saarinen aliangazia ongezeko la eneokazi zilizoundwa(fungua katika dirisha jipya) tulipotoa Symphony. Hata hivyo, mabadiliko ya ndani zaidi ni namna timu zinavyofikiria kuhusu kazi.
Wahandisi wetu wasipotumia tena muda kusimamia vipindi vya Codex, uchumi wa mabadiliko ya kanuni hubadilika kabisa. Gharama inayohisiwa ya kila mabadiliko hushuka kwa sababu hatuwekezi tena juhudi za binadamu katika kuendesha utekelezaji wenyewe.
Hilo lilibadili tabia yetu. Sasa imekuwa rahisi sana kuanzisha kazi za majaribio katika Symphony. Jaribu wazo, chunguza refactor, pima nadharia, na uhifadhi tu matokeo yanayoonekana kuwa ya kuahidi.
Pia hupanua ni nani anaweza kuanzisha kazi. Meneja wetu wa bidhaa na mbunifu sasa wanaweza kufungua maombi ya vipengele moja kwa moja ndani ya Symphony. Hawahitaji ku-check out repo au kusimamia kipindi cha Codex. Wanaeleza kipengele na kupata kifurushi cha ukaguzi kinachojumuisha video ya kupitisha kipengele hicho kikifanya kazi ndani ya bidhaa halisi.
Symphony pia hung'ara katika monorepo kubwa (kama ile tuliyo nayo OpenAI) ambapo hatua ya mwisho ya kuunganisha PR huwa polepole na dhaifu. Mfumo hufuatilia CI, hufanya rebase inapohitajika, hutatua migogoro, hujaribu tena ukaguzi usiotabirika, na kwa ujumla huongoza mabadiliko kupitia pipeline. Tiketi inapofikia Merging, tunakuwa na uhakika mkubwa kwamba mabadiliko yataingia kwenye tawi kuu bila uangalizi wa karibu wa binadamu.
Maendeleo huja na matatizo mapya, tofauti
Kufanya kazi katika kiwango hiki kuna mabadilishano. Tulipohama kutoka kuwaelekeza mawakala kwa mwingiliano hadi kuwapa kazi katika kiwango cha tiketi, tulipoteza uwezo wa kuwasukuma kila mara wakiwa katikati ya kazi na kurekebisha mwelekeo inapohitajika. Wakati mwingine wakala alitoa kitu kilichokosa kabisa lengo. Hilo lilikuwa na manufaa—mifeli hiyo ilifichua mapengo katika mfumo na kutusaidia kuufanya uwe imara zaidi.
Badala ya kurekebisha matokeo kwa mkono, tuliongeza guardrails na ujuzi ili mawakala waweze kufanikiwa wakati ujao. Kadri muda ulivyopita, hili lilituongoza kuongeza uwezo mpya kwenye harness yetu, kama kuendesha majaribio ya end-to-end, kuendesha programu kupitia Chrome DevTools, na kusimamia smoke tests za QA. Tuliboresha sana nyaraka zetu na kufafanua zaidi sura ya kazi nzuri ilivyo.
Si kila kazi inafaa mtindo wa kazi wa Symphony. Baadhi ya matatizo bado yanahitaji wahandisi kufanya kazi moja kwa moja na vipindi vya Codex vya mwingiliano, hasa matatizo yenye ukungu au kazi inayohitaji uamuzi thabiti na utaalamu. Kwa vitendo, hizi ndizo kazi ambazo kwa kawaida huwa za kuvutia zaidi na za kufurahisha zaidi kwa wahandisi wetu kutumia muda wao.
Tofauti ni kwamba Symphony inaweza kushughulikia sehemu kubwa ya kazi ya kawaida ya utekelezaji. Hilo huwaruhusu wahandisi kuzingatia tatizo moja gumu kwa wakati mmoja badala ya kubadili muktadha kila mara kati ya kazi ndogo ndogo.
Pia tulijifunza kwamba kuwachukulia mawakala kama nodi ngumu ndani ya state machine hakufanyi kazi vizuri. Miundo inakuwa nadhifu zaidi na inaweza kutatua matatizo makubwa kuliko kisanduku tunachojaribu kuwabana nacho. Kwa mfano, matoleo ya awali yalikuwa na integrations zote za GitHub kama sehemu ya harness ya nje—kwa mfano, matoleo ya awali yalitarajia Codex ifanye tu mabadiliko ya kanuni, huku sehemu iliyobaki ya mchakato (kuwasilisha mabadiliko, kuendesha majaribio) ikibainishwa katika kanuni. Matoleo yetu ya awali ya kazi za kiwakala yalikuwa yakiiomba Codex kutekeleza kazi tu. Mbinu hiyo ilionekana kuwa na mipaka mno. Codex ina uwezo kamili wa kuunda PR nyingi pamoja na kusoma mrejesho wa ukaguzi na kuushughulikia. Kwa hiyo tuliipa zana—CLI ya gh, ujuzi wa kusoma kumbukumbu za CI, n.k.—na sasa tunaweza kuiomba Codex ifanye zaidi, kama kufunga PR za zamani au kuvuta ripoti za kazi zilizokamilika dhidi ya zilizoachwa. Aina hizi za kazi zilikuwa nje kabisa ya kisanduku cha awali cha utekelezaji wa kipengele.
Kwa hiyo hatimaye tulielekea kuwapa mawakala malengo badala ya transitions kali, sawa na jinsi meneja mzuri angegawa lengo kwa mtu anayemripoti moja kwa moja kwenye timu yake. Nguvu ya miundo hutokana na uwezo wao wa kufanya uwazaji, kwa hiyo wape zana na muktadha na waache wafanye yao.
Kutumia Symphony kujenga Symphony
Unapofungua uhifadhi wa Symphony, jambo la kwanza utakalogundua ni kwamba kitaalamu Symphony ni faili la SPEC.md tu—ufafanuzi wa tatizo na suluhisho lililokusudiwa. Badala ya kujenga mfumo changamano wa usimamizi, tulifafanua tatizo na suluhisho lililokusudiwa, tukiwapa mawakala uelekezaji wa kiwango cha juu.
Utekelezaji wa marejeleo umeandikwa kwa Elixir—kwa sababu kanuni inapokuwa karibu bure, hatimaye unaweza kuchagua lugha kulingana na ubora wake, kama vile concurrency ya Elixir—lakini wazo kuu linaweza kuelezwa katika hati rahisi ya Markdown. Tunakuhimiza uelekeze wakala wako wa uandishi wa kanuni unayependa kwenye spec na umfanye atekeleze toleo lake mwenyewe.
Toleo la kwanza la Symphony lilikuwa tu kipindi cha Codex kinachoendeshwa ndani ya tmux, kikichunguza Linear na kuzindua mawakala wadogo kwa kazi mpya. Kilifanya kazi, lakini hakikuwa cha kutegemewa sana. Toleo la pili liliishi ndani ya uhifadhi wetu mkuu wa mradi, ambao ulijengwa kwa kuzingatia mawakala. Tulikuwa tayari tumetengeneza harness ya wakala ili kuwapa mawakala ujuzi na muktadha wa kufanya kazi ya ubora wa juu katika repo hii, kwa hivyo Symphony iliunganisha tu kila kitu.
Mara tu utendaji wa msingi ulipokuwepo, tulitumia Symphony kuijenga Symphony.
Tulipoonyesha ndani ya kampuni mfumo ukisimamia kazi na kuambatisha video yake ya uthibitisho wa kazi, mwitikio ulikuwa chanya sana: chaneli ya mradi wetu wa Symphony ilikua, na timu kote katika shirika zilianza kuitumia kwa njia ya asili. Internal product market fit ni sharti la kuzindua nje ya OpenAI. Kutokana na matumizi tuliyoona OpenAI, ilidhihirika wazi kwamba tulipaswa kushiriki Symphony nje ya kuta za kampuni.
Kwa hiyo tulitoa wazo hilo na kulifanya kuwa SPEC.md huru na tukaiomba Codex ilitekeleze. Kwa utekelezaji wa marejeleo, tulichagua Elixir, lugha yenye matumizi ya nishe kiasi lakini yenye primitive bora sana za kuoratibu na kusimamia michakato sambamba. Codex ilijenga utekelezaji wa Elixir kwa mkupuo mmoja, na kuanzia hapo tuliendelea kuboresha spec na utekelezaji. Ili kupiga msasa spec, hata tuliomba Codex iteekeleze katika lugha nyingine kadhaa—TypeScript, Go, Rust, Java, Python—na kutumia matokeo kubaini ukungu wowote na kurahisisha mfumo. Ilifaulu katika kila lugha.
Kupitia mchakato wa kujenga Codex, tuliondoa ugumu mwingi usio wa lazima, kama vile utegemezi kwa hifadhi mahususi au Linear MCP. Symphony haitegemei tena hifadhi zetu za ndani au workflows zetu. Mbinu kuu ikawa rahisi:
Kwa kila kazi iliyo wazi, hakikisha kwamba wakala anaendeshwa katika eneokazi yake mwenyewe.
Mbali na kusaidia kazi inayoendelea, workflow ya maendeleo sasa ni kitu ambacho mawakala wanakijua na kukifuata. Workflow ya maendeleo—fanyia kazi issue, check out repo, iweke kuwa inaendelea ili PM ajue inafanyiwa kazi, ongeza PR, ihamishe hadi hali ya Review, ambatisha video, n.k.—sasa imenakiliwa katika faili rahisi la WORKFLOW.md. Haya yote yalikuwa mchakato ambao binadamu walifuata, lakini haukuwa umeandikwa popote. Badala ya kutegemea seti hii fiche ya hatua, sasa tunaiandika, na Symphony huhakikisha mawakala wanaifuata. Hili huturuhusu kujenga mawakala wanaofanya kazi pamoja nasi. Tukiamua kwamba mawakala wanapaswa pia kuambatisha tafakari binafsi kwenye kazi iliyokamilika, tutaongeza hilo kwenye WORKFLOW.md, na Symphony itawaongoza mawakala hadi hatua hiyo.
Pia tuliweza kutumia Codex katika app server mode(fungua katika dirisha jipya), hali ya ndani ya headless ya Codex. Hali hii ilituruhusu kuendesha Codex na kuwasiliana nayo kiprogramu kupitia API ya JSON-RPC iliyoandikwa vizuri kwa mambo kama kuanzisha thread au kuitikia zamu. Ni njia rahisi zaidi na inayoweza kukua kuliko kujaribu kuwasiliana na Codex kupitia CLI au vipindi vya moja kwa moja vya tmux.
Codex App Server ilifaa kikamilifu matumizi yetu: tunatumia harness ambayo Codex hutoa huku tukiwa na knobs na hooks za kuunganisha. Kwa mfano, ili kuepuka kufichua tokeni ya ufikiaji ya Linear kwa mawakala wadogo, tunatumia dynamic tool calls(fungua katika dirisha jipya) kufichua kazi ghafi ya linear_graphql ambayo hutekeleza maombi yoyote dhidi ya Linear, bila kutegemea MCP au kufichua tokeni ya ufikiaji kwa kontena.
Kinachofuata
Symphony ni safu ya uratibu ya kimakusudi iliyo ndogo. Tunaifanya iwe open source ili kuonyesha nguvu ya Codex App Server inapounganishwa na zana tofauti za workflow, kama Linear. Kwa hivyo, hatuna mpango wa kuitunza Symphony kama bidhaa huru. Iwaze kama utekelezaji wa marejeleo. Sawa na jinsi watengenezaji wengi walivyoelekeza mawakala wao wa uandishi wa kanuni kwenye chapisho la harness engineering ili kusanifu hifadhi zao, tunatumaini utaelekeza wakala wako wa uandishi wa kanuni unayependa kwenye spec(fungua katika dirisha jipya) na uhifadhi(fungua katika dirisha jipya) wa Symphony ili ujenge matoleo yako mwenyewe yaliyoboreshwa kwa mazingira yako.
Nguvu hutoka kwa Codex na app server yake. Symphony ilikuwa njia ya kuunganisha Codex na Linear, vitu viwili ambavyo tayari tulikuwa tukitumia, ili kutatua tatizo la usimamizi wa kazi. Kadri mawakala wa uandishi wa kanuni wanavyozidi kuwa bora katika uwazaji na kufuata maelekezo, tunahisi kikwazo katika kampuni nyingine kitahama kutoka kuandika kanuni na kuelekea kusimamia kazi za kiwakala pia. Jambo la kusisimua ni kwamba kizingiti cha kujaribu mifumo hii ya mawakala wa uandishi wa kanuni sasa kiko chini kwa kushangaza. Unaweza tu kujenga vitu kwa Codex.
Shukrani kwa jamii
Tunafurahi sana kuona jamii ya uhandisi ikitumia Symphony katika wiki tangu kutolewa kwake, ikiwa imepata zaidi ya nyota 15K za GitHub(fungua katika dirisha jipya) kufikia Aprili 23.