Alusta AI-ga arendamist
Seadistusjuhend disaineritele, kes pole varem GitHubi, Verceli ega Convexit kasutanud. Repositoorium asub GitHubis ja selle puhas kohalik koopia sinu Macis. Klõpsad läbi mõne rakenduse, avad ühe korra Terminali ja lased Claude Code’il ülejäänu viipade põhjal teha. Lõpuks on sul päris rakendus, iga muudatuse eelvaatelink ning mitu Conductoris kõrvuti töötavat agenti.
Loe {{llms_url}} ja kasuta seda agentidega arendamise käsiraamatu alusena. Kui vajad rohkem üksikasju, järgi seal olevaid linke. Küsi, millise seadistussammu juures ma olen ja mida olen juba teinud, seejärel juhenda mind järgmise sammu kaudu üks tegevus korraga. Peatu alati, kui pean midagi klõpsama või kinnitama, ning ära liigu ette.Kaheksa tööriista, igaühel oma ülesanne
Agentidega arendades kirjeldad muudatust ja mudel teeb töö: loeb faile, käivitab käske, muudab koodi ning kontrollib tulemust. Koodi tippimise asemel on sinu töö selgete ülesannete kirjutamine ja tulemuste ülevaatamine. Need tööriistad võimaldavad seda turvaliselt mitu korda päevas teha.
Maci rakendus, mis käitab korraga mitut agenti, igaüht oma repositooriumi koopias.
Agent. See töötab Conductoris sinu Claude’i paketiga.
Talletab koodi ja selle ajaloo. Muudatused saabuvad PR-idena.
Kloonib repositooriumid sinu Maci ja näitab ajalugu, ilma et peaksid Git käske tippima.
Üks vp käsk arendusserveri, koostamise, lintimise, vormindamise ja testide jaoks.
Sinu repositooriumisse kopeeritud komponendid, mis põhinevad Base UI primitiividel.
TypeScriptis kirjutatud taustateenus ja andmebaas sinu kasutajaliidese kõrval.
Majutab rakendust. Loob igale PR-ile eelvaatelingi.
my-app
├── .agents/skills/ iga oskus: design-review, open-pr, pre-review, ci-watch ja teised
├── .claude/ lingid neile oskustele Claude Code'i jaoks, lisaks alamagendid
├── .conductor/settings.toml iga tööruumi seadistus- ja käivitusskriptid
├── .github/ CI töövood ja pull request'i mall
├── convex/ taustsüsteemi funktsioonid, skeem, algandmed ja testid
├── docs/ arhitektuur, otsused ja juhendid, üks mall
├── e2e/ Playwrighti suitsutestid
├── scripts/ Verceli koostamis- ja vahelejätmisreeglid eelvaate taustsüsteemidele
├── src/components/ ui/ shadcnile, features/ kõigele, mida lood
├── AGENTS.md juhised, mida iga agent loeb
├── CLAUDE.md Claude Code'i sisenemispunkt, impordib faili AGENTS.md
├── components.json shadcni konfiguratsioon
├── vercel.json suunab Verceli ülalolevatele skriptidele
└── vite.config.ts Vite+ konfiguratsioon: dev, build, lint, format, test
Enamikku sellest ei loo sa käsitsi. Selle ehitavad kaheksa viipa sammudes 5–11.
Mõisted, mida kohtad
Git käske pole vaja õppida. Neid käitavad GitHub Desktop, Conductor ja agent. Mõisteid pead aga tundma, sest need ilmuvad igal ekraanil.
| Mõiste | Mida see sinu jaoks tähendab |
|---|---|
| Repositoorium (repository) | Projekti kaust koos kogu ajalooga, mida talletatakse GitHubis. Sageli öeldakse lihtsalt repo. |
| Kloonimine (clone) | Repo allalaadimine GitHubist sinu Maci, et saaksid sellega töötada. |
| Sissekanne (commit) | Salvestatud hetkepilt muudatustest koos lühikese sõnumiga. |
| Haru (branch) | Eraldi tööliin. Muudad seal asju töötavat rakendust puudutamata. |
main | Töötav haru. Muudatused peaksid selleni jõudma PR-i kaudu. |
| Pull request (PR) | Taotlus haru ühendamiseks haruga main. Siin teed ülevaatuse. |
| Worktree | Repo teine koopia teises kaustas ja oma harus. Conductor nimetab seda tööruumiks ning annab igale tööruumile linna nime. |
| Eelvaatejuurutus | Privaatne URL, mille Vercel loob PR-i jaoks, et saaksid muudatuse läbi klõpsata. |
| Arendusjuurutus | Convex taustateenus ja andmebaas arendamiseks. Tarbekeskkond on eraldi. |
| Juurutusvõti | Saladus, mis lubab Vercelil koostamise ajal sinu Convexi taustateenuse üles laadida. |
| Kontekstiaken | Kõik, mida agent ühes vestluses „näeb”: sinu sõnumid, loetud failid ja käsuväljund. |
Miks mitte üks pikk vestlus
Kõige lihtsam tundub avada Claude Code üks kord ja ehitada kogu rakendus ühes vestluses. Esimese tunni jooksul toimib see suurepäraselt. Siis hakkab agent otsuseid unustama, vigu kordama ja muutma faile, mida ta ei peaks puutuma. See pole halb õnn, vaid nende mudelite tööviis.
Mis on kontekstiaken
See on kõik, mida mudel korraga näeb: tema enda juhised, AGENTS.md ja CLAUDE.md, sinu sõnumid, iga avatud fail ning iga loetud käsuväljund. Mahtu mõõdetakse tokenites ehk sõnast veidi lühemates tekstiosades. Claude Code’i dokumentatsioon kasutab näitena 200 000 tokeniga akent, mõne mudeli aken mahutab miljon tokenit. Midagi ei kao märkamatult. Kui aken saab täis, tihendab Claude Code vestluse kokkuvõtteks ja üksikasjad kaovad.
Illustratsioon põhineb Anthropic’u kontekstiakna näitel. Üks väike veaparandus kasutab 200 000 tokenist umbes 19 000: ligikaudu 7900 laaditakse enne, kui midagi sisestad, 7600 kulub failidele ja reeglitele, 2000 käsuväljundile, 1400 muudatustele ja vastustele ning alla 100 sinu enda sõnumitele.
Üks väike veaparandus
umbes 19K tokenit 200K-stOsuta osale, et näha selle sisu.Süsteemiviip, CLAUDE.md, oskuste loend, mälu4 lähtefaili, 2 reeglitgrep, testikäivitus, vormindaja haagid2 muudatust, 1 kokkuvõte1 viip, 1 täpsustus
Kümme sellist parandust täidavad akna ja käivitavad tihendamise, mis kirjutab vanimad parandused ruumi tegemiseks ümber üheks lühikeseks kokkuvõtteks.
Kümme parandust hiljem samas vestluses
Tihendamine. Vanimad parandused kirjutatakse ruumi tegemiseks ümber lühikeseks kokkuvõtteks. Esimese paranduse ajal kokkulepitu mahub nüüd heal juhul ühte lausesse.
Alamagendiga
eraldi akenTagasi tuleb ainult vastus. Loetud failid jäävad alamagendi enda aknasse, nii et sinu vestlus püsib väike.
Arvud pärinevad Claude Code’i dokumentatsioonis olevast Anthropic’u interaktiivsest kontekstiakna näitest.
Üks pikk vestlus või iga ülesande jaoks oma tööruum
Üks pikk vestlus
1 haruIga ülesande jaoks oma tööruum
4 haruIdee illustratsioon, mitte jõudlustest. Tegelik ajakulu oleneb sellest, kui kiiresti sa töö üle vaatad.
Kontekstiaken on piiratud ressurss
Iga sõnum, faililugemine ja käsuväljund jääb vestlusse. Anthropic’u Claude Code’i juhend ütleb otse: Claude’i kontekstiaken täitub kiiresti ja jõudlus halveneb selle täitudes.
Chroma testis 18 mudelit ning leidis, et jõudlus muutub sisendi pikenemisel aina ebausaldusväärsemaks.
Tihendamine kaotab üksikasjad
Kui aken saab täis, teeb Claude Code vestlusest ruumi vabastamiseks kokkuvõtte. Dokumentatsioon ütleb hinna selgelt välja: tööriistade täielikud väljundid ja vahepealne arutluskäik kaovad.
Kaks tundi tagasi kokku lepitud vahereegel säilib ebamäärase lausena või ei säili üldse.
Kõigest saab üks muudatus
Üks vestlus ühes harus lõpeb ühe hiiglasliku PR-iga. Valmis kuva ei saa avaldada, kuni katkine kuva ootab, ning üht funktsiooni ei saa tagasi võtta ilma teisi tühistamata.
Sa ootad järjekorras
Üks agent teeb korraga üht asja. Kui igal ülesandel on oma tööruum, töötavad kolm agenti samal ajal, kui vaatad üle esimesena valminud töö. Värske vestlus teeb ka parema ülevaatuse: Claude ei eelista koodi lihtsalt seetõttu, et kirjutas selle ise.
Millal on üks vestlus õige valik. Ühes tööruumis peaks olema töö, mis tuleb avaldada koos, näiteks uus andmebaasiväli ja seda kasutav kuva. Conductori dokumentatsioon soovitab kasutada üht tööruumi, kui töö kasutab sama haru, koodi olekut ja konteksti.
Jaga töö selle järgi, mida saab eraldi avaldada, mitte failitüübi järgi.
Iga töö jaoks oma mudel
Mudelid erinevad arutluse sügavuse ja hinna poolest. Tugevaimad mudelid tasuvad end ära seal, kus vale otsus on kallis: kavandamisel, töö jaotamisel ja ülevaatamisel. Kavandatud muudatuse kirjutamiseks või koodibaasist otsimiseks pole neid vaja. Conductor võimaldab valida igale vestlusele Claude Code’i või Codexi mudeli, nii et saad neid kombineerida.
Illustratsioon. Alamagentidel on oma kontekstiaknad, seega ei jõua nende loetud materjal põhivestlusse.
| Töö | Kus see töötab | Mudel |
|---|---|---|
| Kavandamine, jaotamine, ülevaatus | Vestlus, kuhu kirjutad, kavandamisrežiimiga (⇧Tab) | Tugevaim saadaolev mudel: Claude Opus või suure arutlustasemega Codex |
| Ühe kavandatud osa ehitamine | Üks implementer-alamagent | Sonnet. Anthropic’u dokumentatsiooni järgi saab see enamiku programmeerimisülesannetega hästi hakkama ja maksab vähem kui Opus |
| Koodi otsimine, logide lugemine | Kasuta Explore-alamagenti | Haiku, kiire ja lugemiseks soodne |
| Koodi ülevaatus | Conductori toiming Review | Koodi kirjutanud mudelist erinev mudel, näiteks Codex vaatab üle Claude’i töö |
| Väikesed ja ilmsed muudatused | Suvaline vestlus kiirrežiimis | Sinu jaoks kõige kiirem mudel |
- Vali mudel Conductori igas vestluses eraldi. Sisestusvälja mudelivalija loetleb Claude Code’i ja Codexi mudelid. Vaikeväärtused asuvad failis
~/.conductor/settings.toml:models.defaultuute vestluste jamodels.reviewülevaatuste jaoks. - Anna alamagentidele oma mudel. Alamagent on fail kaustas
.claude/agents/, milles on ridamodel:. Claude Code annab talle töö, kui ülesanne vastab tema kirjeldusele või kui nimetad ta ise. 9. sammu viip 6 lisab Sonnetigaimplementer-agendi ja HaikugaExplore-agendi. - Palu töö orkestreerida. Viiba 6 oskus
orchestratekäsib põhivestlusel töö kavandada, delegeerida iga osa täieliku lähteülesandega ja tulemused ise üle vaadata. Sisesta enne suuremat ülesannet/orchestrate. - Väljaspool Conductori. Terminalis töötavas Claude Code’is kasutab
/model opusplankavandamisrežiimis Opust ja ehitamise alustamisel Sonnetit.
Miks see paketi puhul oluline on. Opuse tokenid maksavad rohkem, seega kulutab see paketi piirangud kiiremini ära. Kasuta Opust otsuste tegemiseks ning lase mahukas töö teha Sonnetil ja Haikul, et sama paketiga rohkem ülesandeid lõpetada.
Conductori sees
Suurema osa ajast veedad selles aknas. Mõlemad kuvatõmmised pärinevad Conductori veebisaidilt ning numbrid vastavad iga pildi all olevatele märkustele.
Tööruum ülesande täitmise ajal

Kogu akna nägemiseks libista külgsuunas.
- Tööruumid. Igal ülesandel on oma rida, haru ja repo koopia, nii et agendid ei muuda kunagi samu faile.
- Vestluste vahekaardid. Sama tööruumi vestlused jagavad selle faile. Ava ülevaatuse või kiire küsimuse jaoks teine vahekaart.
- Agendi tehtud töö. Tööriistakutsed näitavad loetud faile, käivitatud käske ja tehtud muudatusi. Ava need, kui tulemus tundub vale.
- Sisestusväli. Kirjuta ülesanne, märgi failid @-märgiga ja lisa kuvatõmmis klahvidega ⌘U. Selle all on mudel, kiirrežiim, arutlustase ja kavandamisrežiim.
- Pull request. Kui PR on loodud, kuvatakse siin selle number ja olek. Soovitatud toiming muutub töö edenedes ning lõpeb ühendamisega.
- Muudatused, kontrollid ja ülevaatus. Muudatuste vaade loetleb muudetud failid koos lisatud ja eemaldatud ridadega. Kontrollide vaade koondab CI, juurutused, kommentaarid ja ülesanded. Ülevaatus palub agendil erinevuse üle vaadata.
- Käivitamine ja Terminal. Käivitamine alustab faili
.conductor/settings.tomlkäivitusskripti selle tööruumi enda pordil (⌘R). Terminal avab käsurea otse tööruumis.
Kuvatõmmis saidilt conductor.build. See pärineb teise mudeliga meeskonnakontolt, seega ei vasta loend Team ega mudeli nimi sinu omadele.
Täiesti uus tööruum
Seda näed kohe pärast ⌘N vajutamist, enne kui midagi sisestad.

Kogu akna nägemiseks libista külgsuunas.
- Tööruum. See on nimetatud linna järgi. Linna nimi on ketta kausta nimi, haru nimi kirjeldab tööd.
- Uus koopia. Repo Git worktree. Sinu klooni kaustas
~/Developerei puudutata. - Värske haru uusimast
origin/mainolekust. Teisest PR-ist sõltuv töö peaks ootama, kuni see PR ühendatakse. - Failid. Giti jälgitavad failid tuuakse tööruumi. Eiratud failid, näiteks
.env.local, kopeeritakse ainult siis, kui need vastavad kopeeritavate failide seadistusele, mille vaikeväärtus on.env*. - Seadistusskript. Failist
.conductor/settings.toml: paigaldab paketid ja loob selle tööruumi Convexi taustateenuse. Logi avamiseks klõpsa sellel. - Kõik failid, muudatused ja kontrollid. Null muudatust tähendab, et midagi pole veel muudetud. Agendi töötades täitub see loend.
- Seadistamine, käivitamine ja Terminal. Seadistamise vahekaart säilitab seadistusskripti väljundi. Käivitamise vahekaart jääb tühjaks, kuni vajutad ⌘R.
- Sisestusväli.
@viitab failidele,#PR-idele ning/käskudele ja oskustele, näiteks/pre-review.
Kuvatõmmis pärineb Conductori dokumentatsioonist.
Kontod
- GitHub. Loo tasuta konto aadressil github.com. Kõigisse teistesse teenustesse logid sisse selle kontoga.
- Tehisintellekti pakett. Claude Code’i jaoks Claude Pro või Max, Codexi jaoks ChatGPT pakett. Conductor käitab mõlemat ning mudeli valid iga vestluse jaoks eraldi, seega alustamiseks piisab ühest. Selle juhendi oskused on kirjutatud Claude Code’i jaoks, Codex loeb faili AGENTS.md.
- Vercel. Registreeru aadressil vercel.com valikuga Continue with GitHub.
- Convex. Logi aadressil dashboard.convex.dev GitHubiga sisse.
Conductori jaoks pole vaja kontot luua. Kohalikud tööruumid on tasuta ning rakendus kasutab sinu enda Claude’i või ChatGPT paketti, seega teist tehisintellekti arvet ei tule.
Paigalda rakendused
- GitHub Desktop. Laadi see alla aadressilt desktop.github.com, paki lahti, ava ja logi GitHub.com-i sisse.
- Conductor. Laadi see alla aadressilt conductor.build ja lohista kausta Applications. Ära seda veel ava.
Üks kord Terminalis
Conductor kontrollib GitHubi GitHub CLI kaudu, agendid vajavad projekti tööriistade käitamiseks Node.js-i ning agent-browser võimaldab neil ehitatud tulemust vaadata. Ava Terminal (⌘ Space, sisesta Terminal) ja kleebi need käsud ükshaaval. Edaspidi käitab käske agent.
Mis on Homebrew. Homebrew on tasuta paigaldaja, mida enamik arendajaid Macis kasutab. See sarnaneb Terminalis kasutatava App Store’iga. Esimene allolev käsk paigaldab Homebrew enda. Seejärel lisab brew install tööriistu, näiteks GitHub CLI ja Node.js-i, ning brew upgrade hoiab need ajakohasena.
# Homebrew, the installer for developer tools. It asks for your Mac password.
~ % /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
# GitHub CLI, Node.js and agent-browser
~ % brew install gh node agent-browser
# Claude Code and Vite+
~ % curl -fsSL https://claude.ai/install.sh | bash
~ % curl -fsSL https://vite.plus | bash
Enne järgmist plokki. Homebrew lõpetab jaotisega Next steps. Käita seal loetletud käsud, sulge Terminal ja ava uus aken, et süsteem leiaks uued tööriistad.
- Paigaldusplokk on valmis. Kõik neli käsku töötasid vigadeta.
- Järgmised sammud tehtud. Käitasid Homebrew käsud ja avasid uue Terminali akna.
# Answer: GitHub.com, HTTPS, Yes, Login with a web browser
~ % gh auth login
# Signs in to your Claude account in the browser. Type /exit when it's done.
~ % claude
# Signs in to Convex so agents can create backends for you
~ % npx convex login
# Downloads the Chrome that agent-browser drives
~ % agent-browser install
# Context7: current library docs for Claude Code. Signs in with the browser.
~ % npx ctx7 setup --claude --mcp
- Sisse logitud. GitHub, Claude, Convex ja Context7 avasid brauseri ning kinnitasid sisselogimise, agent-browser lõpetas Chrome’i allalaadimise.
See oligi kogu Terminali osa. Sulge see.
Brauser agentidele
agent-browser on programmeerimisagentidele loodud käsureabrauser. Agent avab selles sinu arendusserveri, muudab akna telefoni laiuseks, liigub tabeldusklahviga läbi kuva, klõpsab põhitoimingut ning teeb kuvatõmmised, mida ise vaatab. 5. sammu oskus design-review kontrollib sellega kujundust enne, kui avad erinevuse, ning 6. sammu oskus open-pr lisab samad kuvatõmmised PR-ile.
Ajakohane dokumentatsioon agentidele
Mudelid õpivad veebi kindla ajahetke koopiast, kuid Vite+, Base UI ja Convex muutuvad sellest kiiremini. Context7 on MCP-server ehk pistikprogramm, mis annab agentidele tööriista. See otsib teegi ajakohast dokumentatsiooni ja koodinäiteid, et agent kontrolliks tegelikku API-t ega oletaks mälu põhjal. Viimane käsk lõi tasuta konto ja ühendas selle.
| Asukoht | Mida see sisaldab |
|---|---|
| ~/.claude.json | Context7 server ja sinu enda API-võti kõigile selle Maci projektidele. Selle kirjutab ctx7 setup. |
| ~/.claude/rules/context7.md | Reegel, mis käsib Claude Code’il kasutada teekide dokumentatsiooni, seadistamise ja konfiguratsiooni jaoks Context7-t. |
| AGENTS.md, repos | Sama võtmeta reegel kõigile agentidele ja meeskonnakaaslastele. Selle lisab 5. sammu seadistusviip. |
Kas kasutad Codexit? Käita ka npx ctx7 setup --codex --mcp. See kirjutab serveri faili ~/.codex/config.toml ja reegli faili ~/.codex/AGENTS.md. Meeskonnakaaslased käitavad samad käsud oma kontoga, nii et ühtki võtit ei jagata ega lisata commiti.
Loo GitHubis ja klooni Maci
Repo saab alguse GitHubis, kus asub jagatud koopia, millest kõik muudatusi tõmbavad. Seejärel kloonib GitHub Desktop selle kohalikku kausta, kus Conductor ja agendid töötavad. Käske pole vaja.
Loo repo saidil github.com
- Ava github.com/new. Omanik oled sina või võimaluse korral sinu meeskonna organisatsioon.
- Pane nimeks
my-appja vali Private. - Lisa README, vali faili .gitignore väärtuseks Node, jäta litsents vahele ja klõpsa Create repository.
Hoia koodi väljaspool kausta Documents
Ära klooni kausta Documents ega Desktop. GitHub Desktop soovitab kausta Documents sees asuvat kausta. Kui iCloudi säte Desktop & Documents Folders on sisse lülitatud, sünkroonitakse need kaustad iCloudi. iCloud ei suuda Giti sisemisi faile õigesti ühildada ning repo võib saada vea, näiteks fatal: bad object. Optimize Mac Storage võib vähese ruumi korral failid ka Macist eemaldada. Varukoopia asub GitHubis, seega ei tohiks koodikausta mujale sünkroonida.
- Ava Finderis klahvidega ⇧⌘H oma kodukaust.
- Vali File, seejärel New Folder ja pane kausta nimeks
Developer. Kõik kloonitavad projektid lähevad siia.
Klooni GitHub Desktopiga
- Ava GitHub Desktop, seejärel Settings ja Git. Kontrolli oma nime, vali GitHubi kontoga seotud e-posti aadress ja klõpsa Save. Need andmed lisatakse igale commitile.
- Vali File ja seejärel Clone Repository. Vali vahekaardil GitHub.com repo
my-app. - Klõpsa välja Local Path kõrval Choose ja vali kaust Developer. Asukoht peaks lõppema tekstiga
/Developer/my-app. - Klõpsa Clone.
| Asukoht | Mis seal asub |
|---|---|
| github.com/you/my-app | Jagatud koopia. PR-id, ülevaatused ja ajalugu. |
| ~/Developer/my-app | Sinu põhikaust, mille kloonis GitHub Desktop. See jääb harusse main. |
| ~/conductor/workspaces/my-app | Iga Conductori tööruumi jaoks üks kaust, igaüks oma harus. Agendid töötavad siin. |
| .env.local | Kohalikud saladused, näiteks Convexi URL. Git eirab neid ja neid ei laadita kunagi üles. |
| ~/.claude | Sinu isiklikud Claude Code’i seaded ja oskused, mida jagavad kõik projektid. |
| Convex cloud | Iga tööruumi arenduse taustateenus ning eelvaate ja tarbekeskkonna taustateenused. |
Kas liitud kellegi teise projektiga? Jäta github.com-i osa vahele. Klooni nende repo samamoodi kausta Developer ja jätka 4. sammuga. Sammude 5 ja 6 viibad on tõenäoliselt juba ühendatud.
Lisa repo Conductorisse
- Ava Conductor. Selle seadistuskontrollid otsivad GitHubi ja Claude Code’i sisselogimisi. Pärast 2. sammu peaksid mõlemad õnnestuma.
- Lisa repositoorium (⌘⌥A), vali Open project ja seejärel
~/Developer/my-app. - Conductor loob uues harus tööruumi, millel on kaustas
~/conductor/workspacesoma kaust. Seal agent töötabki. - Context7 on ühendatud. Sisesta tööruumi vestlusse
/mcp-statusja otsi context7 kirjet. Kui seda pole, klõpsa sisestusväljal pistikuikooni ja värskenda.
Üks haru, üks asukoht. GitHub Desktop näitab sinu põhikausta. Git lubab haru korraga välja võtta ainult ühes kaustas, seega ära vali GitHub Desktopis haru, mida kasutab Conductori tööruum. Jäta see harule main ja kasuta ajaloo vaatamiseks.
Üks seadistusviip
Kleebi see esimesse tööruumi. See ehitab algrakenduse, lisab Vite+ koos lintimisega ning kirjutab agendi juhised ja Conductori seaded. Kõik tehakse ühes harus, et saaksid üle vaadata ja ühendada ühe PR-i. Loetletud teadaolevad probleemid on päriselt olemas: kõik neli ilmnesid seadistuse katsetamisel ning nende nimetamine säästab agenti oletamisest.
Seadista see repo ühes harus ja ühe PR-ina: rakendus, Vite+ koos lintimisega, agendi juhised ja Conductori seaded. Säilita README.md ning ühenda faili .gitignore sisu, mitte ära asenda seda. Tee iga osa järel commit. 1. osa: rakendus 1. shadcn CLI ei saa luua algrakendust kausta, kus on juba faile. Käita ajutises kaustas npx shadcn@latest init -t vite --base base --preset nova --name my-app, tõsta seejärel kõik peale .git selle repo sisse ja käita npm install. 2. Võta Vite+ kasutusele käsuga npx -p vite-plus vp migrate --no-interactive. 3. Lisa Convex. Olen juba sisse logitud. Leia minu meeskonna slug käsuga npx convex login status, seejärel loo uus projekt nimega my-app koos pilves töötava arendusjuurutusega, kasutades käsu npx convex dev --once mitteinteraktiivseid lippe (vaata --help). 4. Mähi rakendus failis src/main.tsx komponendiga ConvexProvider, kasutades muutujat VITE_CONVEX_URL. 5. Käita npx convex ai-files install, npx skills add shadcn/ui --yes ja npx skills add vercel-labs/agent-browser --yes. 6. Lisa vercel.json, mille buildCommand on npx convex deploy --cmd-url-env-var-name VITE_CONVEX_URL --cmd 'npm run build', et Vercel juurutaks iga koodi üleslaadimise puhul taustateenuse ja saidi koos. Vite+ 0.3.2 teadaolevad probleemid. Kui neid kohtad, paranda need: 1. package.json devEngines seob npm 12 väärtusega onFail "download", mistõttu npm 10 ja 11 keelduvad töötamast. Muuda onFail väärtuseks "warn". 2. vite.config.ts sisaldab lintimise seadetes allowCompoundComponents, mis rikub TypeScripti koostamise. Eemalda see rida. 3. Linter märgib failis vite.config.ts identifikaatori __dirname veaks ja blokeerib commitid. Kasuta import.meta.dirname. 4. vp check teatab kaustas src/components/ui reegli react/only-export-components rikkumisest, sest shadcn failid ekspordivad komponentide kõrval variante. Lisa src/components/ui jaoks lintimise erand, mis lülitab selle reegli välja, ja paiguta see overrides-loendi lõppu. 2. osa: agendi juhised. Hoia kõik failid lühikesed. 1. CLAUDE.md: lisa esimesele reale @AGENTS.md, et Claude Code loeks ka faili AGENTS.md. Lisa selle alla jaotis "Claude Code": kasuta faili convex/schema.ts muutmisel kavandamisrežiimi ning käita pärast kasutajaliidese tööd oskus design-review. Säilita Convexi plokk. 2. AGENTS.md: lisa faili algusse Vite+ ja Convexi plokkide kohale projekti jaotis. Loetle faili package.json tegelikud käsud. Kasutajaliidese reeglid: lisa komponente shadcn CLI-ga; komponendid kasutavad Base UI-d, seega ära kunagi impordi paketti @radix-ui; värvid, ümardused ja vahed pärinevad faili src/index.css CSS-i muutujatest; igal kuval on laadimise, tühja sisu ja vea olekud. 3. AGENTS.md, dokumentatsioonireegel: kui Context7 on ühendatud, otsi enne Vite+, Base UI, shadcn/ui, Convexi või mõne muu teegi jaoks koodi kirjutamist selle ajakohane dokumentatsioon. 4. AGENTS.md, oskuste reegel: repo oskused asuvad failides .agents/skills/NAME/SKILL.md, kust Codex neid loeb, ning Claude Code’i jaoks on asukohas .claude/skills/NAME suhteline sümbollink. Seda struktuuri kasutas juba npx skills add. 5. Oskus design-review on kleebitud selle viiba alla. Salvesta see failina .agents/skills/design-review/SKILL.md, loo link ning kontrolli selle käske ja asukohti selle repo põhjal. Lisa .screenshots/ faili .gitignore. Oskus kasutab agent-browserit, mille paigaldasin Homebrewga; kontrolli, et agent-browser --version töötab. 3. osa: Conductor. Loo .conductor/settings.toml aadressil https://conductor.build/schemas/settings.repo.schema.json oleva skeemi põhjal. 1. Seadistusskript: npm ci, seejärel anna tööruumile oma Convexi arendusjuurutus käsuga npx convex deployment create --type=dev TEAM:PROJECT:dev/$USER-conductor/$CONDUCTOR_WORKSPACE_NAME --select --expiration "in 14 days". Täida TEAM ja PROJECT käsu npx convex login status ning faili .env.local põhjal. 2. Vaikimisi käivitusskript nimega dev: npx convex dev --start "npm run dev -- --port $CONDUCTOR_PORT --strictPort". 3. Määra run_mode väärtuseks "concurrent" ja git.archive_on_merge väärtuseks true. 4. Lisa .conductor/settings.local.toml faili .gitignore. Käivita iga CLI mitteinteraktiivselt (CI=1), et miski ei jääks sisendit ootama. Töö on valmis, kui npm run build ja npx vp check läbivad kontrolli ning kõik kolm osa on commititud.
---
name: design-review
description: Check UI changes against our design rules, then look at them in a real browser with agent-browser. Use after building or changing a screen, before the open-pr skill, or when asked to polish UI.
---
# Design review
Most design bugs only show on screen. Read the code, fix what breaks the
rules, then open every changed screen in a browser and look at it.
This skill edits files. It never commits.
## 1. Find the screens
```bash
git fetch origin --quiet
git diff --name-only $(git merge-base origin/main HEAD) -- src
git diff --name-only -- src
```
List the routes those files render. If no screen changed, stop and say so.
## 2. Read the code
| Check | Rule |
| ---------------------- | ----------------------------------------------------- |
| Color, radius, spacing | CSS variables from src/index.css, no hex or px values |
| Components | From src/components/ui, built on Base UI, no @radix-ui |
| States | Loading, empty and error for every query |
| Copy | Sentence case, no placeholder text |
Fix what fails before opening the browser.
## 3. Look at it
Start the dev server if it isn't running, on this workspace's port. Use
agent-browser. If you're unsure of a command, run
`agent-browser skills get core` once. Save images to `.screenshots/`, which
git ignores.
```bash
agent-browser open http://localhost:$PORT/tasks
agent-browser set viewport 1440 900
agent-browser screenshot .screenshots/tasks-desktop.png
agent-browser set viewport 375 812
agent-browser screenshot --full .screenshots/tasks-mobile.png
agent-browser set media dark
agent-browser screenshot .screenshots/tasks-mobile-dark.png
```
`set media dark` works when the theme follows the system. If the app has a
theme toggle instead, click it. Skip dark when the app has no dark mode.
Open every image and look at it:
1. Nothing overlaps, clips or runs off the edge at 375 wide.
2. Spacing, alignment and type sizes match the screens around it.
3. Text and icons are readable in light and dark.
4. The data has loaded. No spinner, error or sign-in page.
## 4. Use it
```bash
agent-browser snapshot -i
agent-browser press Tab
agent-browser eval "document.activeElement.outerHTML"
agent-browser click @e2
agent-browser screenshot .screenshots/tasks-add-dialog.png
agent-browser eval "document.documentElement.scrollWidth > innerWidth"
agent-browser errors
agent-browser console
agent-browser close
```
1. Tab through the screen. Every control shows a visible focus ring, in
reading order.
2. Click the main action and screenshot what opens.
3. The scroll check prints false at 375 wide.
4. errors and console show nothing new from this change.
If a state can't be reached in the browser, say which one instead of
guessing. Without agent-browser, take the screenshots in step 3 with
`npx playwright screenshot --viewport-size "375, 812" URL FILE` and say that
step 4 was skipped.
## 5. Gates
```bash
npx vp check
npm run build
```
## Reply
A short list: what you fixed, the screenshot paths, and anything you
couldn't check. Leave the screenshots in place for the open-pr skill.
## Never
- Never call a screen checked without opening its screenshot.
- Never hide overflow or shrink text to make a layout fit.
- Never add a hex color, px value or another component library to pass a check.
- Never commit screenshots.
- Kleebi viip ja lase agendil töötada. Agent käitab mõnda aega käske ning teeb iga kolme osa järel commiti. Vasta, kui ta midagi küsib.
- Kontrolli, et tulemus näeb õige välja. Sisesta
/design-review. Agent käivitab arendusserveri, avab agent-browseris alustuskuva töölaua ja telefoni laiuses ning vastab tehtud paranduste ja kuvatõmmistega. - Avalda muudatus. Ava erinevus (⌘⇧D), loo PR (⌘⇧P) ja ühenda see (⌘⇧M). Erinevus on hiiglaslik, sest sisaldab kogu algrakendust. Järgmised PR-id peaksid olema väikesed.
- Uued tööruumid on valmis. Loo üks klahvidega ⌘N. Selle seadistusskript käivitub ise ning annab tööruumile taustateenuse ja pordi.
Ühendatud rakenduse nägemiseks põhikaustas klõpsa GitHub Desktopis esmalt Fetch origin ja seejärel Pull origin.
Mida seadistus lisab
| Fail | Milleks seda kasutatakse | Millal see laaditakse |
|---|---|---|
| AGENTS.md | Codexi, Cursori, Copiloti ja kümnete teiste agentide ühised reeglid. Vite+ ja Convex kirjutavad samuti oma jaotised. | Igal seansil |
| CLAUDE.md | Claude Code loeb faili CLAUDE.md, mitte faili AGENTS.md, seega impordib esimene rida faili AGENTS.md. | Igal seansil |
| .agents/skills | Oskuste kaustad, millest igaühes on tegevusjuhis SKILL.md. Codex loeb neid siit. shadcn ja agent-browser paigaldavad enda omad, viip lisab oskuse design-review. | Kui oskus on asjakohane või sisestad /name |
| .claude/skills | Lingid samadele kaustadele, et Claude Code loeks üht koopiat, mitte teist ajapikku lahknevat koopiat. | Sama |
| .conductor/settings.toml | Kirjeldab, mida Conductor tööruumi loomisel ja nupu Run vajutamisel käitab. | Igas uues tööruumis |
| vercel.json | Käsib Vercelil juurutada Convexi taustateenuse koos saidiga. | Igal juurutusel |
Hoia juhisefailid lühikesed. Need laaditakse igasse vestlusse ja kulutavad konteksti. Anthropic’u kontrollküsimus igale reale on: Kas selle eemaldamine paneks Claude’i vigu tegema? Kui ei, eemalda see.
Püsi alla 200 rea. Kohanda viiba 2. osa ühiseid reegleid oma tegeliku tööviisi järgi.
Pull request'i reeglid
Kui repo pole reegleid määranud, kasutavad viis PR-e avavat agenti viit eri nimetamisviisi. See viip paneb reeglid üks kord kirja: haru ja pealkirja vormingu, PR-i malli ning kuvatõmmiseid lisava oskuse, et saaksid kasutajaliidese muudatuse üle vaadata otse PR-i lehel.
| Mis | Vorming | Näide |
|---|---|---|
| Haru | type/short-slug | feat/task-comments |
| PR-i pealkiri | type(scope): summary | feat(tasks): add comments to tasks |
| Sisu | PR-i mall | Mis muutus, miks, kuvatõmmised, kuidas testida, kontrollid, märkused |
| Kuvatõmmised | Kasutajaliidese muudatustest laiusega 1440 ja 375 | tasks-desktop.png, tasks-mobile.png |
Tüüp on feat, fix, refactor, docs, test või chore. Pealkirjad järgivad Conventional Commitsi vormingut, mida muudatuste logi ja väljalasketööriistad juba loevad.
Kus reeglid asuvad
| Fail | Kes seda loeb |
|---|---|
| AGENTS.md, jaotis Pull requests | Iga agent igal seansil. |
| .agents/skills/open-pr | Codex ja .claude/skills lingi kaudu Claude Code. Käivitub iga PR-i loomisel või uuendamisel. |
| .github/pull_request_template.md | GitHub, mis täidab sellega uue PR-i ette, ja oskus open-pr. |
| .conductor/settings.toml, [prompts] | Conductor, mis saadab need haru ümbernimetamise ja Create PR-i toimingutega. |
Kuvatõmmised ilma sinuta. agent-browser on agentidele loodud käsureabrauser. See avab tööruumi arendusserveri, saab sisse logida või voo läbi klõpsata ning salvestab ekraani pildina; varuvariant on Playwright. Alates versioonist 2.99.0 laadib GitHub CLI --attach need pildid otse PR-i kirjeldusse.
Viip 2: pull request'i reeglid
Käivita see uues tööruumis pärast seadistuse PR-i ühendamist. Viiba kopeerimisel lisatakse mõlemad allolevad failid.
Lisa pull request'i reeglid, et iga agent nimetaks harusid ja pealkirju ning täidaks PR-e ühtemoodi, lisades kasutajaliidese muudatustele kuvatõmmised. Selle viiba all on selles järjekorras kaks faili. 1. Salvesta need failidena .github/pull_request_template.md ja .agents/skills/open-pr/SKILL.md ning lingi oskus kausta .claude/skills/open-pr samamoodi nagu teised oskused. Kontrolli iga käsku ja teed selle repo järgi ning paranda sobimatu. 2. AGENTS.md: lisa jaotis Pull requests. Üks ülesanne haru kohta. Harude nimed on kujul type/short-slug ja PR-i pealkirjad kujul type(scope): summary, kasutades oskuse open-pr tüüpide tabelit. Iga PR täidab malli ning kasutajaliidese muudatustele lisatakse töölaua ja mobiili kuvatõmmised. Kasuta PR-i loomiseks või uuendamiseks oskust open-pr. 3. .conductor/settings.toml: lisa tabel [prompts]. rename_branch käsib nimetada haru kujul type/short-slug, kasutades AGENTS.md tüüpe. create_pr käsib järgida oskust open-pr. 4. Kontrolli, et gh --version oleks 2.99.0 või uuem, ja kui ei ole, käivita brew upgrade gh. Tee commit ja kasuta sellel harul oskust open-pr. Selle PR järgib uusi reegleid esimesena.
- Viip 2 töötab uues tööruumis.
- Selle enda PR järgib reegleid. Haru algab
chore/, pealkirichore:võichore(repo):ning kirjelduses on kõik malli jaotised. Kuvatõmmiseid pole, sest ükski kuva ei muutunud. - Squash-ühendamised kasutavad pealkirja. Ava github.com-is repo Settings, General ja Pull Requests. Hoia Allow squash merging sees ning määra vaikesõnumiks Pull request title.
- Viip 2 on ühendatud. Sinu järgmise kasutajaliidese muudatuse PR sisaldab kuvatõmmiseid.
## What changed
<!-- One or two sentences a reviewer can check against the preview. -->
## Why
<!-- The problem or request. Link the issue if there is one. -->
## Screenshots
<!-- UI changes only, desktop 1440 and mobile 375. Otherwise write None. -->
| Desktop | Mobile |
| ------- | ------ |
| | |
## How to test
<!-- Steps to follow on the Vercel preview link. -->
1.
## Checks
- [ ] `npx vp check` and `npm run build` pass
- [ ] Tests added or updated
- [ ] Loading, empty and error states
- [ ] Docs updated if behaviour changed
## Notes
<!-- Schema changes, new environment values, follow-ups. Otherwise None. -->
---
name: open-pr
description: Create or update a pull request that follows this repo's branch names, title format, template and screenshot rules. Use when a branch is ready for review, when asked to open or update a PR, or from Conductor's Create PR action.
---
# Open a PR
One task per PR. This skill checks the branch name, writes the title and body
from the template, attaches screenshots of changed screens and opens the PR.
## 1. Branch name
Format: `type/short-slug`. Lowercase, 2 to 4 words joined by hyphens.
| Type | Use for |
| -------- | --------------------------------------- |
| feat | A new screen, feature or behaviour |
| fix | A bug fix |
| refactor | Code change with no behaviour change |
| docs | Only docs/ and *.md |
| test | Only tests |
| chore | Config, dependencies, tooling and CI |
Examples: `feat/task-comments`, `fix/sign-in-redirect`.
Rename before the first push with `git branch -m type/short-slug`.
Never rename a branch that already has a PR.
## 2. Title
Conventional Commits: `type(scope): summary`.
- Same type as the branch.
- Scope is the feature folder or area, like `tasks` or `auth`. Leave it out
when the change has none.
- Summary is imperative, lowercase, no period, under 60 characters.
Examples: `feat(tasks): add comments to tasks`, `fix(auth): keep redirect after sign-in`.
## 3. Screenshots
Needed when the diff changes what a screen looks like or does. Skip them for
backend-only, docs, tests and config changes.
1. If the design-review skill already saved screenshots of these screens in
`.screenshots/` on this branch, reuse them and skip to step 4.
2. Start the dev server if it isn't running. Use this workspace's port.
3. Capture every changed screen at 1440x900 and at 375x812. Add dark mode
when the app has it. Use seed data.
4. Save to `.screenshots/`, named `screen-size.png`, like `tasks-desktop.png`.
With agent-browser (check `agent-browser --version`):
```bash
agent-browser open http://localhost:$PORT/tasks
agent-browser set viewport 1440 900
agent-browser screenshot .screenshots/tasks-desktop.png
agent-browser set viewport 375 812
agent-browser screenshot .screenshots/tasks-mobile.png
agent-browser close
```
It can also sign in, click and fill forms first, when the change sits behind
a flow. Without it, use Playwright:
```bash
npx playwright screenshot --viewport-size "1440, 900" http://localhost:$PORT/tasks .screenshots/tasks-desktop.png
npx playwright screenshot --viewport-size "375, 812" http://localhost:$PORT/tasks .screenshots/tasks-mobile.png
```
Open every image before attaching it. It must show the change, not a loading
spinner, an error or the sign-in page.
## 4. Body
Write `.screenshots/pr-body.md` from `.github/pull_request_template.md`.
Keep every section. Write None instead of deleting one. In the Screenshots
table, reference each image by the same path you attach:
``.
## 5. Open or update
`--attach` needs gh 2.99.0 or later. Check `gh --version`; if it's older,
run `brew upgrade gh`.
```bash
git push -u origin HEAD
gh pr create --title "feat(tasks): add comments to tasks" \
--body-file .screenshots/pr-body.md \
--attach ./.screenshots/tasks-desktop.png \
--attach ./.screenshots/tasks-mobile.png
```
If the branch already has a PR, run `gh pr edit` with the same flags. gh
uploads each image and swaps the local path in the body for its link.
Reply with the PR link and title. If the repo has a ci-watch skill, run it next.
## Never
- Never commit screenshots. `.screenshots/` is ignored by git.
- Never capture real user data, keys or tokens.
- Never delete a template section to shorten the body.
- Never tick a checklist box you didn't verify.
Ühenda Vercel
Ühendad Verceli ühe korra ja edaspidi toimuvad juurutused ise. Iga harusse lükkamine loob eelvaate, iga ühendamine harusse main uuendab tarbekeskkonda ning CI kontrollib mõlemat. Ainus käsitsi tehtav osa on kahe erineva võtme kopeerimine Convexist Vercelisse nii, et kumbki kehtib ainult ühes Verceli keskkonnas.
Milline võti kuhu läheb
Tarbekeskkonna juurutusvõti
üks projekti kohta- Hangi siit
- Convex, tarbekeskkonna juurutus, Settings
- Näeb välja nii
prod:your-deployment|…- Kleebi siia
- Vercel, Settings, Environment Variables, nimega
CONVEX_DEPLOY_KEY, tüüp Secret - Keskkonnad
- TarbekeskkondEelvaadeArendus
- Tulemus
- Harusse main ühendamine juurutab tarbekeskkonna taustsüsteemi
Eelvaate juurutusvõti
üks projekti kohta- Hangi siit
- Convex, projekti seaded
- Näeb välja nii
preview:team:project|…- Kleebi siia
- Vercel, Settings, Environment Variables, nimega
CONVEX_DEPLOY_KEY, tüüp Secret - Keskkonnad
- TarbekeskkondEelvaadeArendus
- Tulemus
- Iga pull request'i haru saab oma taustsüsteemi
Sama nimi, kaks väärtust, kummalgi üks valik. Vercel lubab samal muutuja nimel olla igas keskkonnas eri väärtus ja sellel lahendus põhinebki. Kui tarbekeskkonna võtmel on valitud ka Preview, juurutab iga pull request otse sinu tarbekeskkonna taustsüsteemi. Development jääb valimata: sinu Mac ja Conductori tööruumid kasutavad sinu Convexi sisselogimist ning GitHub Actions ei vaja üldse Convexi võtit.
Tee ära
- Vali Convexi töölaual oma tarbekeskkonna juurutus, ava Settings ja klõpsa Generate Production Deploy Key. Kopeeri see. Võti algab
prod:. - Ava vercel.com/new ja impordi GitHubist
my-app. Kui seda loendis pole, anna Vercelile sellele repole ligipääs. - Kontrolli, et Framework Preset oleks Vite. Ära muuda Build Commandi: selle määrab seadistusviiba loodud
vercel.json. - Lisa jaotises Environment Variables tarbekeskkonna võtmega
CONVEX_DEPLOY_KEYja klõpsa Deploy. Esimene juurutus peaks õnnestuma. - Ava Verceli projektis Settings ja seejärel Environment Variables. Kustuta see
CONVEX_DEPLOY_KEYning lisa uuesti: tarbekeskkonna võti, tüüp Secret ja keskkondade all ainult Production. - Mine tagasi Convexisse, ava juurutuse asemel projekti seaded ja klõpsa Generate Preview Deploy Key. Võti algab
preview:. - Lisa Vercelisse teist korda
CONVEX_DEPLOY_KEY: eelvaate võti, tüüp Secret ja ainult Preview. - Kontrolli loendit. Vercel näitab muutujat
CONVEX_DEPLOY_KEYkaks korda: üks kehtib Productionis ja teine Preview's ning Developmenti jaoks pole midagi. Edaspidi ei juuruta keegi terminalist.
{
"buildCommand": "npx convex deploy --cmd-url-env-var-name VITE_CONVEX_URL --cmd 'npm run build'"
}
Vercel käivitab selle igal juurutusel. convex deploy loeb keskkonnale vastava CONVEX_DEPLOY_KEY: tarbekeskkonna võti juurutab tarbekeskkonna, eelvaate võti loob harule taustsüsteemi. Samm 11 asendab selle näidisandmetega skriptiga.
Kõik juhendis kasutatavad väärtused
Seadeid hoitakse kolmes kohas ja igaüks piiritleb neid erinevalt. Vercel piirab muutuja Productioni, Preview või Developmenti keskkonnaga ning küsib tüüpi: Secret peidab väärtuse pärast salvestamist, Config jääb loetavaks. GitHub jagab Actionsi seaded vahekaartideks Secrets, mille väärtused on peidetud ja logides varjatud, ning Variables. Convex hoiab igal juurutusel eraldi väärtusi; projekti Settingsi all olevad vaikeväärtused kopeeritakse loomisel uutesse arendus- ja eelvaatejuurutustesse, olemasolevad säilitavad oma varasemad väärtused.
| Väärtus | Kuhu see läheb | Tüüp |
|---|---|---|
CONVEX_DEPLOY_KEYSina, samm 7 | Tarbekeskkonna võtiTarbekeskkondEelvaadeArendus | Salajane |
CONVEX_DEPLOY_KEYSina, samm 7 | Eelvaate võti, sama nimiTarbekeskkondEelvaadeArendus | Salajane |
VERCEL_ENV, VERCEL_BRANCH_URL ja ülejäänudVercel automaatselt | Midagi pole vaja lisadaTarbekeskkondEelvaadeArendus | Süsteem |
VERCEL_AUTOMATION_BYPASS_SECRETSina, samm 8 | Secrets-vahekaart, New repository secret. Vercel lisab selle juba oma juurutustesse | Salajane |
CONVEX_AGENT_MODEViip 7 | Kirjutatud faili ci.yml. CI ei vaja Convexi võtit | Seadistus |
APP_ENVViiba 7 skript, seejärel sina | preview eelvaate vaikeväärtusena, production tarbekeskkonnasArendusEelvaadeTarbekeskkond | Seadistus |
SITE_URLSkriptid | Eelvaated: vercel-build.sh. Arendus ja tarbekeskkond: lisatakse sisselogimisviibagaArendusEelvaadeTarbekeskkond | Seadistus |
BETTER_AUTH_SECRETSisselogimisviip | Eri juhuslik väärtus arenduse vaikeväärtustele, eelvaate vaikeväärtustele ja tarbekeskkonnaleArendusEelvaadeTarbekeskkond | Privaatne |
RESEND_API_KEY, RESEND_WEBHOOK_SECRETSina, Resendist | Ainult tarbekeskkond. Arendus ja eelvaated jäävad testrežiimiArendusEelvaadeTarbekeskkond | Privaatne |
POLAR_ORGANIZATION_TOKEN, POLAR_WEBHOOK_SECRET, POLAR_SERVERSina, Polarist | Liivakasti väärtused arenduse ja eelvaate vaikeväärtustena, päris väärtused tarbekeskkonnasArendusEelvaadeTarbekeskkond | Privaatne |
AI-teenusepakkuja võti, näiteks ANTHROPIC_API_KEYSina | Ainult ilma Convex AI Gatewayta. Mitte kunagi sinu Maci kestasse, kus Claude Code võtaks selle eest tasuArendusEelvaadeTarbekeskkond | Privaatne |
Sinu agendi seadedSinu Macis, väljaspool repot | ||
Context7 API võtinpx ctx7 setup, samm 2 | Kirjutatakse faili ~/.claude.json ning Codexi jaoks faili ~/.codex/config.toml. Igaüks kasutab enda oma. Mitte kunagi reposse, Vercelisse ega GitHubi | Salajane |
CONVEX_DEPLOYMENTSeadistusskript | Millist arenduse taustsüsteemi see tööruum kasutab | Seadistus |
VITE_CONVEX_URL, VITE_CONVEX_SITE_URLConvex CLI | CLI kirjutab need kohapeal. Vercelis sisestab convex deploy mõlemad. Ära määra neid kunagi Vercelis | Avalik |
Kolm reeglit. Kõik, mis algab VITE_, jõuab JavaScripti, mille iga külastaja alla laadib, seega ei tohi see kunagi saladust sisaldada. Ära määra Vercelis kunagi VITE_CONVEX_URL, sest see kirjutaks sisestatud väärtuse üle. Ära ka commit'i võtit ega kleebi seda vestlusse: git eirab faili .env.local põhjusega.
Testid ja CI
Agendid liiguvad kiiresti, seega peab turvavõrk olema automaatne. Kogenud tarkvarainsener seadistaks esimesel päeval just selle: kiired kontrollid iga commit'i korral, kolme taseme testid igal pull request'il ja suitsutest päris juurutuse vastu. See annab agentidele ka asja, mille Anthropic Claude Code'i juhendis esikohale seab: kontrolli, mida see saab käivitada
.
Pull request'i kontrollid
5 kontrolli/ci-watch.Mida ikoonid tähendavad
GitHub ja ConductorIllustratsioon. Samad kontrollid on näha GitHubi pull request'il ja Conductori vahekaardil Checks.
| Kiht | Tööriist | Käivitub | Leiab |
|---|---|---|---|
| Staatilised kontrollid | vp check: Oxlint, Oxfmt, TypeScript | Iga commit, iga PR | Tüübivead, lindi reeglid, vormindus |
| Ühik | Vitest Node'is | Iga PR | Abifunktsioonide ja hook'ide loogika |
| Taustsüsteem | convex-test keskkonnas edge-runtime | Iga PR | Päringud, mutatsioonid, valideerimine |
| Komponendid | Vitest Browser Mode, päris Chromium | Iga PR | Renderdamine, klõpsud, keelatud ja fookuse olekud |
| Läbiv | Playwright juurutatud rakenduse vastu | Pärast iga Verceli juurutust | Koostamisvead, keskkonnamuutujad ja marsruutimine |
Miks komponendid vajavad päris brauserit. jsdom ainult jäljendab brauserit. Vitesti dokumentatsioon ütleb: Et teste võimalikult kindlalt usaldada, on hädavajalik testida päris brauserikeskkonnas.
Selle hind on aeglasem käivitus ja see ei asenda täielikult eraldiseisvaid läbivate testide käitajaid
, mistõttu on olemas suitsutesti kiht.
Viip 3: testikomplekt
Käivita see uues tööruumis. Teadaolev probleem ilmnes just selle seadistuse testimisel.
Seadista testimine nii, nagu seda teeks kogenud tarkvarainsener. Kasuta Vite+'i (vp test käivitab Vitesti) ja hoia kogu testide seadistus failis vite.config.ts. 1. Lisa test-plokki kolm Vitesti projekti: "unit" failidele src/**/*.test.ts keskkonnas node, "convex" failidele convex/**/*.test.ts keskkonnas edge-runtime ja "components" failidele src/**/*.test.tsx Browser Mode'is Playwrighti pakkuja ning ilma kasutajaliideseta Chromiumiga. Impordi pakkuja asukohast vite-plus/test/browser-playwright. 2. Arendussõltuvused: @vitest/browser-playwright ja @vitest/coverage-v8, kinnitatuna käsu vp toolchain vitest Vitesti versioonile, lisaks playwright, @playwright/test, vitest-browser-react, convex-test ja @edge-runtime/vm. Seejärel vp exec playwright install chromium. 3. Katvus v8 pakkujaga kaustadele src ja convex, jättes välja convex/_generated ning testifailid. Lisa coverage, test-results ja playwright-report faili .gitignore. 4. Esimesed päris testid: ühiktest abifunktsioonile, convex-test'i test igale olemasolevale päringule ja mutatsioonile (import.meta.glob, faili alguses /// <reference types="vite/client" />) ning brauseritest komponendile Button kaustas src/components/ui. 5. Playwrighti suitsutest: playwright.config.ts, kus testDir on e2e, baseURL pärineb muutujast BASE_URL või kohaliku käsu vp preview tulemusest pordil 4173 webServeri kaudu, CI määramisel korduskatsed ja githubi reporter ning VERCEL_AUTOMATION_BYPASS_SECRET määramisel päis x-vercel-protection-bypass. Üks e2e/smoke.spec.ts, mis laadib avalehe ilma lehevigadeta. Lisa playwright.config.ts ja e2e faili tsconfig.node.json. 6. .conductor/settings.toml: lisa käivitusskript nimega test, mis käivitab npx vp test watch. 7. AGENTS.md: loogikatestid asuvad faili kõrval kujul *.test.ts, kasutajaliidese testid kujul *.test.tsx ja töötavad päris brauseris ning Convexi testid asuvad kaustas convex/. Muudatus on valmis, kui vp check ja vp test õnnestuvad. Teadaolev probleem. Linter teatab Playwrighti failides, et process pole defineeritud. Lisa failidele playwright.config.ts ja e2e/** lindi erand keskkonnaga node. Valmis siis, kui vp check, vp test ja vp exec playwright test kõik õnnestuvad. Seejärel tee commit.
- Viip 3 töötab uues tööruumis.
- Kõik kolm projekti õnnestuvad. Väljund loetleb unit, convex ja components (chromium).
- Viip 3 on ühendatud. CI vajab neid teste harus main enne viipa 4.
Viip 4: GitHub Actions
Käivita see tööruum pärast viiba 3 ühendamist, et CI saaks oma PR-is teste käivitada.
Lisa sellesse reposse GitHub Actionsi CI, järgides GitHubi turvalisuse tugevdamise juhiseid. 1. .github/workflows/ci.yml käivitub pull_request'il ja harusse main lükkamisel. Kolm paralleelset tööd: "Lint, format, types" käivitab vp check. "Tests" käivitab vp exec playwright install --with-deps chromium, seejärel vp test run --coverage ja laadib katvuse üles artefaktina, mida hoitakse 7 päeva. "Build" käivitab vp run build. 2. Iga töö kasutab voidzero-dev/setup-vp koos node-version "24" ja cache: true. Ära kasuta kunagi selle silti v1. 3. Kinnita iga action täielikule commit'i SHA-le ja lisa kommentaari väljalaskesilt. Vaata praegused väljalasked käsuga git ls-remote --tags. 4. Ülataseme õigused: contents: read. Checkout koos persist-credentials: false. Igal tööl timeout-minutes ning concurrency-grupp, mis tühistab sama PR-i vanemad käivitused. 5. .github/workflows/e2e-smoke.yml sündmusel repository_dispatch tüübiga vercel.deployment.success: tee checkout väärtusele github.event.client_payload.git.sha ja käivita vp exec playwright test, kasutades muutujas BASE_URL väärtust github.event.client_payload.url ning repo saladustest muutujat VERCEL_AUTOMATION_BYPASS_SECRET. 6. .github/dependabot.yml iganädalaste rühmitatud uuendustega github-actionsi ja npm-i jaoks. 7. .github/CODEOWNERS määrab mind (gh api user --jq .login) kausta /.github/ omanikuks. Valideeri mõlemad töövood actionlintiga. Seejärel tee commit.
- Viip 4 töötab uues tööruumis.
- Selles PR-is on kolm rohelist kontrolli. Lint, vorming, tüübid; testid; koostamine. Need on näha ka Conductori vahekaardil Checks.
- Viip 4 on ühendatud.
name: CI
on:
pull_request:
push:
branches: [main]
permissions:
contents: read
concurrency:
group: ci-${{ github.event.pull_request.number || github.ref }}
cancel-in-progress: ${{ github.event_name == 'pull_request' }}
jobs:
check:
name: Lint, format, types
runs-on: ubuntu-latest
timeout-minutes: 10
steps:
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1"t-cm"> # v7.0.1
with:
persist-credentials: false
- uses: voidzero-dev/setup-vp@d5616419e3a9637febec6da1475cee9d07a317fd"t-cm"> # v1.20.0
with:
node-version: "24"
cache: true
- run: vp check
test:
name: Tests
runs-on: ubuntu-latest
timeout-minutes: 15
steps:
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1"t-cm"> # v7.0.1
with:
persist-credentials: false
- uses: voidzero-dev/setup-vp@d5616419e3a9637febec6da1475cee9d07a317fd"t-cm"> # v1.20.0
with:
node-version: "24"
cache: true
- name: Install Chromium for component tests
run: vp exec playwright install --with-deps chromium
- run: vp test run --coverage
- uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a"t-cm"> # v7.0.1
if: ${{ !cancelled() }}
with:
name: coverage
path: coverage/
retention-days: 7
build:
name: Build
runs-on: ubuntu-latest
timeout-minutes: 10
steps:
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1"t-cm"> # v7.0.1
with:
persist-credentials: false
- uses: voidzero-dev/setup-vp@d5616419e3a9637febec6da1475cee9d07a317fd"t-cm"> # v1.20.0
with:
node-version: "24"
cache: true
- run: vp run build
| Rida | Miks kogenud tarkvarainsener selle lisab |
|---|---|
| SHA kinnitused | GitHub: Actioni kinnitamine täielikule commit'i SHA-le on praegu ainus viis kasutada actionit muutumatu väljalaskena.Dependabot hoiab need ajakohasena. |
| permissions: contents: read | Töövoo luba saab lugeda koodi ja mitte midagi muud. |
| persist-credentials: false | Luba ei jää checkout'i, kust hilisemad sammud selle kätte saaksid. |
| concurrency | Uus lükkamine tühistab sama PR-i vana käivituse, nii et sageli lükkavate agentide tõttu ei teki pikkade minutite pikkust järjekorda. |
| timeout-minutes | Kinni jäänud brauseritest ebaõnnestub kuue tunni kulutamise asemel minutitega. |
| Kolm tööd | Need töötavad paralleelselt ja ebaõnnestuvad eraldi, nii et PR näitab täpselt, mis katki läks. |
GitHub Actionsis töötades muudab Vitest ebaõnnestumised ise PR-i muudetud ridade märkusteks.
Muuda CI väravaks
- Ava github.com-is repo Settings. Ava külgriba jaotise Code and automation alt Rulesets. Klõpsa New ruleset ja seejärel New branch ruleset.
- Määra Enforcement status väärtuseks Active ja lisa sihtmärk Include default branch.
- Lülita sisse Require a pull request before merging ja Require status checks to pass. Lisa
Lint, format, types,TestsjaBuild, seejärel klõpsa Create.
Kontrolli paketti. Rulesets töötab avalikes repodes paketiga GitHub Free, kuid privaatne repo vajab paketti GitHub Pro, Team või Enterprise. Ilma selleta CI siiski töötab ja näitab punast või rohelist, kuid ei saa ühendamisnuppu blokeerida.
Juurutuse suitsutest
- Ava Vercelis projekti Settings, seejärel Deployment Protection ja loo saladus Protection Bypass for Automation.
- Ava github.com-is repo Settings, seejärel Secrets and variables ja Actions. Klõpsa vahekaardil Secrets, mitte Variables, nuppu New repository secret ning pane nimeks
VERCEL_AUTOMATION_BYPASS_SECRET. - Suitsutest käivitus. Pärast järgmist juurutust ilmub repo vahekaardile Actions käivitus "E2E smoke after deploy".
Pea meeles kahte asja. Vercel käivitab selle sündmuse ainult siis, kui töövoofail on harus main juba olemas. Kuna sündmus töötab haru main kontekstis, kuvatakse tulemus Actionsis, kuid see ei piira PR-i; seda teevad CI tööd.
Dokumentatsioon ja ülevaatusoskused
Kaks harjumust takistavad agentidel vigu kordamast: dokumentatsioonikaust, mida nad loevad enne millegi toimimise muutmist, ja oskused, mis kontrollivad töö üle enne diff'i avamist.
Agentidele kasutatav dokumentatsioonikaust
AGENTS.md jääb lühikeseks ja viitab siia. Iga dokument algab samast mallist, nii säilitavad dokumendid ühtse kuju ja on piisavalt lühikesed, et need ühe korraga läbi lugeda.
| Kaust | Lugeja küsib | Max ridu |
|---|---|---|
| architecture/ | Kuidas see on kokku pandud? | 500 |
| decisions/ | Miks me selle valisime? Kirjed on nummerdatud ja neid ei kirjutata kunagi ümber; uus kirje asendab vana. | 300 |
| guides/ | Kuidas ma seda sammhaaval teen? | 600 |
| integrations/ | Kuidas me seda välist teenust kasutame? | 400 |
- Mis ja miks, mitte kuidas. Kood näitab, kuidas. Seda kordav dokument muutub järgmise redigeerimise järel valeks.
- Eelista lõikudele tabeleid ja diagramme. Kolm paralleelset fakti ühes lauses kuuluvad tabelisse.
- Lingi failile, ära kleebi seda. Kleebitud lõik aegub, kuid tee viib endiselt kuhugi.
- Uuenda igal muudatusel välja Last Updated. Vana kuupäev jätab hüljatud mulje.
docs
├── README.md milline kaust millisele küsimusele vastab
├── _template.md ühtne stiil; iga uus dokument algab siit
├── architecture/overview.md kuidas rakendus on üles ehitatud
├── decisions/0001-stack.md miks see tehnoloogiapinu ja mis on selle hind
└── guides/
├── local-setup.md kloonimisest töötava tööruumini
└── preview-deployments.md lisatakse 7. viibaga
<!--
HOUSE STYLE. This block is the rulebook. Copy this file, keep the one section
that matches your document type, delete everything else including this block.
When you copy a section, promote its headings one level: the section's H2
becomes your document's H1, its H3s become H2s. Nothing goes deeper than H3.
SIZE BUDGETS
| Type | Max lines | Target |
| ------------- | --------- | ------- |
| architecture | 500 | 250-350 |
| decisions | 300 | 150-250 |
| guides | 600 | - |
| integrations | 400 | - |
Over budget means the document is doing two jobs. Split it.
RULES
1. WHAT and WHY, not HOW. The code is the how, and it drifts. A document that
restates the implementation is wrong the moment someone edits the file.
2. Tables and Mermaid over prose. If a paragraph has three or more parallel
facts in it, it is a table.
3. Link to source, never paste it: `convex/tasks.ts:42`. Line numbers go
stale, so cite them only where the exact line matters; a bare path is
usually enough. No code snippets except the one or two patterns a guide
cannot express any other way.
4. Heading depth stops at H3.
5. Active voice, present tense. "The build injects the URL", not "the URL will
be injected by the build".
6. Plain English. No marketing voice, no filler sentences that announce what
the next section will say.
7. Emoji carry meaning or stay out. A warning marker on a real pitfall is
fine; decoration is not.
8. Update **Last Updated** when you edit. A document with a stale date is
treated as unmaintained, which is worse than absent.
-->
# Document Title
One or two sentences: what this document covers and who it is for. If you need
three, the scope is too wide.
**Last Updated:** YYYY-MM-DD
---
## Architecture
For: how a part of the system is put together.
### Components
| Component | Responsibility | Source |
| ---------- | ---------------------------------------- | ------------------- |
| App shell | Providers, routing and the Convex client | `src/main.tsx` |
| Tasks | Task reads and writes | `convex/tasks.ts` |
### Data flow
Show the path a request actually takes. One diagram beats four paragraphs.
```mermaid
sequenceDiagram
participant Browser
participant App as React app
participant Convex
Browser->>App: open page
App->>Convex: subscribe (query)
Convex-->>App: initial result
Convex-->>App: push on write
App-->>Browser: re-render
```
### Key decisions
Link the ADR rather than re-arguing it here. One line of summary each.
- Backend is Convex: `docs/decisions/0001-stack.md`.
### Trade-offs
| Choice | Gains | Costs |
| -------------------------- | -------------------------------- | ---------------------------------- |
| shadcn/ui copied into repo | Full control, no upstream breaks | Updates are pulled in by hand |
### Related docs
- `docs/architecture/folder-structure.md`
---
## Decision record
For: a choice that is expensive to reverse. Numbered, and immutable once
accepted. Supersede it with a new record instead of editing the reasoning.
File name: `NNNN-short-slug.md`.
**Status:** Proposed | Accepted | Superseded by NNNN
**Date:** YYYY-MM-DD
**Review Date:** YYYY-MM-DD
### Context
The forces in play when the decision was made: constraints, team size, what was
already true. Written so a reader in a year understands why this looked correct
without needing to have been there.
### Decision
What we do, in the present tense. One paragraph, then the specifics as a list.
### Alternatives
| Option | Why not |
| -------- | ------------------------------------------------------------- |
| Option A | The one concrete reason it lost, not a list of vague concerns |
### Consequences
**Positive**
- What this buys, stated as an effect rather than an intention.
**Negative**
- What it costs. A record with no negative consequences has not been thought
through, and reviewers read an empty list as a warning sign.
### References
- Links to the docs, issues, or benchmarks the decision leaned on.
---
## Guide
For: doing a specific thing, step by step. The only document type where a code
snippet is routinely justified, and still only for the command or pattern that
prose cannot express.
### Prerequisites
- [ ] Access or credential the reader needs before starting
- [ ] Tool installed, with the version that matters
### Overview
What the whole procedure achieves, and when to reach for it.
### Steps
1. **Name the step.** What it does and what "done" looks like.
2. **Name the next.** Commands inline, one line each.
### Code references
| What | Where |
| ---------------------------- | ------------------------- |
| The script this guide drives | `scripts/vercel-build.sh` |
### Common pitfalls
| Symptom | Cause | Fix |
| --------------------------------- | ---------------------- | ---------- |
| The visible thing that goes wrong | The non-obvious reason | The action |
### Testing checklist
- [ ] The observable result that proves it worked
- [ ] The failure case, deliberately triggered
---
## Integration
For: a third-party service we depend on.
### Overview
What the service does for us and which parts of the product break without it.
### Authentication
Credential type, where each one is stored, and its rotation story. Never the
value itself.
### Supported operations
| Operation | Direction | Trigger | Source |
| ----------- | --------- | ------------- | ----------------- |
| Create task | Inbound | User submits | `convex/tasks.ts` |
### Data mappings
| Our field | Their field | Notes |
| ------------ | ---------------- | ---------------------- |
| `user.email` | `customer.email` | Lowercased before send |
### Rate limits
| Limit | Value | Our behaviour on breach |
| ------------------- | ----- | ------------------------------- |
| Requests per minute | 100 | Exponential backoff, then queue |
### Error handling
| Code | Meaning | Our response |
| ---- | ------------------- | ------------------------- |
| 429 | Rate limited | Retry with backoff |
| 401 | Credential rejected | Fail loudly; do not retry |
### Troubleshooting
| Symptom | Check |
| ---------------------- | --------------------------------- |
| Writes silently vanish | Whether the sandbox key is in use |
Kohandatud tootmisrepo mallist. Viiba 5 kopeerimine lisab selle, seega pole vaja seda eraldi kleepida.
Viip 5: dokumentatsioonikaust
Loo sellele repole docs-kaust. Meie mall on kleebitud selle viiba alla. 1. docs/_template.md: salvesta mall täpselt kleebitud kujul. 2. docs/README.md, alla 60 rea: nelja kausta (architecture, decisions, guides, integrations) tabel koos küsimusega, millele igaüks vastab, ja malli reapikkuse piiranguga. 3. Kolm algdokumenti, millest igaüks on kopeeritud sobivast mallijaotisest ja mahub selle piirangusse: docs/architecture/overview.md: kasutajaliides, Convex ja Vercel koos Mermaidi diagrammiga sellest, kuidas muudatus jõuab tarbekeskkonda. docs/decisions/0001-stack.md: miks Vite+, Base UI-l põhinev shadcn/ui, Convex ja Vercel. Päris negatiivsed tagajärjed, mitte tühi loend. docs/guides/local-setup.md: kloonimisest töötava Conductori tööruumini koos seadistus- ja käivitusskriptide ning testide käivitamise juhisega. 4. AGENTS.md: lisa jaotis Docs. Loe docs/README.md enne millegi toimimise muutmist. Kui muudatus muudab dokumendi valeks, paranda dokument samas PR-is ja uuenda Last Updated. Uued dokumendid algavad failist docs/_template.md. 5. Koodi kleepimise asemel lingi lähtefailidele. Kirjuta ainult seda, mida saad repost kinnitada, ja loetle oletamise asemel viimases sõnumis kõik, mida ei saanud kinnitada. Seejärel tee commit.
- Viip 5 töötab uues tööruumis.
- Loe ise üks dokument läbi. Ava diff'is docs/decisions/0001-stack.md. Kui mõni lause ajaks sind segadusse, ajab see segadusse ka järgmise agendi; ütle seda vestluses.
- Viip 5 on ühendatud.
Ülevaatusoskused
Oskus laaditakse, kui selle kirjeldus sobib ülesandega või kui sisestad /name. Need katavad iga ülesande lõpu: loo hea kuva, viimistle see enne PR-i ja lase CI-l ilma sinu järelevalveta roheliseks saada.
| Oskus | Mida see teeb | Millal |
|---|---|---|
| design-review | Sammust 5. Avab iga muudetud kuva agent-browseris töölaua ja telefoni laiusega, liigub tabulaatoriga läbi kuva, loeb konsooli, parandab reeglite rikkumised ning salvestab kuvatõmmised. | Pärast kuva loomist või muutmist |
| frontend-design | Anthropic pluginast pärinev oskus, mis aitab üldise tehisintellektiliku välimuse asemel luua eristuva ja kasutusvalmis kasutajaliidese. | Kuva loomise ajal |
| pre-review | Parandab diff'i vormingu, kustutab tarbetud kommentaarid, kontrollib muudetud faile reeglite järgi, käivitab kõik väravad ja nõuab puuduvat testi. Lõpetab tulemusega PASS või CHANGES REQUIRED. Ei tee kunagi commit'i. | Enne toimingut Create PR |
| ci-watch | Ootab PR-i kontrollide lõppu, loeb ebaõnnestunud kontrolli logi, kordab viga kohapeal, parandab põhjuse ja lükkab muudatuse üles. Lõpetab pärast kolme ringi. | Kohe pärast PR-i avamist |
| orchestrate | Koostab põhimudeliga plaani, saadab alamagentidele Explore (Haiku) otsinguülesanded ja alamagentidele implementer (Sonnet) osade loomise ülesanded ning vaatab seejärel iga diff'i ise üle. | Enne mitut faili hõlmavat ülesannet |
Viip 6: oskused ja alamagendid
Selle viiba kopeerimisel lisatakse kõik viis allolevat faili, nii et agent salvestab katsetatud juhised ega mõtle ise uusi välja. Kaks alamagendifaili seadistavad põhijaotises kirjeldatud mudelirollid.
Lisa ülevaatusoskused, mudelirollid ja Anthropic frontend-designi plugin. Selle viiba all on selles järjekorras viis faili. 1. Salvesta need failidena .agents/skills/pre-review/SKILL.md, .agents/skills/ci-watch/SKILL.md, .agents/skills/orchestrate/SKILL.md, .claude/agents/implementer.md ja .claude/agents/explore.md ning lingi kolm oskust kausta .claude/skills samamoodi nagu teised oskused. Kontrolli iga käsku ja teed selle repo järgi ning paranda sobimatu. Jäta reeglid, Never-loendid ja model: read muutmata. 2. Paigalda frontend-design kogu projekti jaoks: claude plugin install frontend-design@claude-plugins-official --scope project. Kui käsu järgi ei leitud turuplatsi, käivita esmalt claude plugin marketplace add anthropics/claude-plugins-official. Kontrolli, et .claude/settings.json lubaks nüüd selle plugina. 3. AGENTS.md, PR-i reeglites: loo uued kuvad oskusega frontend-design ja kontrolli neid oskusega design-review. Käivita pre-review enne oskust open-pr ning ci-watch pärast muudatuste üleslükkamist. Mitut faili hõlmava töö korral kasuta oskust orchestrate. Kui valmis, tee commit.
- Viip 6 töötab uues tööruumis.
- Proovi seda eraldi harus. Sisesta selles tööruumis enne PR-i
/pre-review. See peaks lõppema otsuse ja reaga Checks. - Viip 6 on ühendatud. Sisesta seejärel oma järgmises PR-is
/ci-watchja lase sellel töötada.
---
name: pre-review
description: Final polish before a PR. Use when a branch is finished and about to become a pull request, or after review feedback is fixed. Fixes what is safe, runs every gate, and returns PASS or CHANGES REQUIRED.
---
# Pre-review
The author's last pass, not the reviewer's first. After a PASS, a reviewer
should find nothing that AGENTS.md, docs/ or CI already knew how to catch.
This skill cites the rules; it does not copy them.
This skill edits files. It never commits, pushes or merges.
## When to run it
| Situation | Run it? |
| -------------------------------------- | ------------------------------ |
| Branch finished, about to open a PR | Yes, once over the whole batch |
| Review feedback fixed | Yes, confirm nothing regressed |
| Halfway through the work | No. Finish first |
## 1. Resolve the diff
```bash
git fetch origin --quiet
BASE_REF=origin/$(gh pr view --json baseRefName --jq .baseRefName 2>/dev/null || echo main)
BASE=$(git merge-base "$BASE_REF" HEAD)
git diff --name-only "$BASE"..HEAD
git diff --name-only; git diff --cached --name-only
git ls-files --others --exclude-standard
```
Never diff against local main. In a worktree it trails origin/main.
## 2. Stop early if
| Condition | Why |
| ------------------------------------------------------ | ------------------------------------- |
| Conflict markers (`git diff --check "$BASE"..HEAD`) | Resolving a merge is the author's call |
| Empty diff | Nothing to review |
| VITE_CONVEX_URL or CONVEX_DEPLOYMENT hand-edited in .env* | This workspace now points at another backend |
## 3. Diff-scoped autofix
```bash
npx vp fmt <changed files>
npx vp lint --fix <changed files>
```
Never format the whole repo. Keep formatting and import-order changes. Read
anything else a fix changed; revert a fix that changes behaviour and fix the
cause by hand. Never silence a rule to pass.
## 4. Comment audit
Only comments added or changed in this diff.
| Comment | Action |
| ------------------------------------------------ | ------ |
| Restates the code or narrates the change | Delete |
| Mentions the PR, branch or ticket | Delete |
| Explains a non-obvious why | Keep |
## 5. Check the diff against the rules
| Touched | Check against |
| -------------------------------- | ---------------------------------------------------------- |
| `convex/**` | Validators on every function's args and returns; queries use an index and `.take()` or pagination, never `.filter()` as the main lookup |
| `convex/schema.ts` | Existing documents still validate. Widen, backfill, then narrow in separate PRs |
| `src/**/*.tsx` | AGENTS.md UI rules, then run the design-review skill |
| `vercel.json`, `scripts/vercel-*` | docs/guides/preview-deployments.md |
| `docs/**` | docs/_template.md house style, folder budget, Last Updated |
| `AGENTS.md`, `.claude/**` | Every command and path it mentions exists |
A changed path that matches no row is a finding: warn and propose a row.
## 6. Convex codegen
Only when `convex/**` changed.
```bash
npx convex codegen
git status --porcelain convex/_generated
```
Changed output is the fix, not a failure. Keep it for the commit.
## 7. Run the gates
```bash
npx vp check
npx vp test run
npm run build
```
All green before a PR. A failure that was already on main is still a blocker:
fix it or report it. Never skip, retry or loosen your way past a gate.
## 8. Missing test
Behaviour changed and no test covers it: blocker. Clear it when you can name
the expected outcome in one sentence.
- Put the test next to the code, on the smallest layer that proves it.
- Prove it fails first: revert the behaviour, see red, restore, see green.
- Never `git stash`. The workspace may hold a human's uncommitted edits.
If the expected outcome is ambiguous, don't guess. Ask one question and return
CHANGES REQUIRED.
## 9. Report
```markdown
## Pre-review: <branch> against <base>
**Verdict:** PASS | CHANGES REQUIRED (N blockers, M warnings)
### Fixed
- vp fmt and vp lint --fix on 4 files
- 2 comments removed
### Blockers
- [MISSING TEST] convex/tasks.ts: toggle() changed, nothing covers it
### Warnings
- docs/guides/local-setup.md still describes the old run script
### Checks
vp check green. vp test green (14 passed). Build green. Codegen current.
### Try it
<what to click at http://localhost:$CONDUCTOR_PORT and what should happen>
```
Lead with a missing-test blocker when there is one. PASS only at zero blockers.
## Never
- Commit, push or merge.
- Format or fix files outside the diff.
- Use --no-verify, force-push, or git stash.
- Skip or weaken a test, or add a retry, to get a gate green.
---
name: ci-watch
description: Watch a pull request's checks until they finish, then fix failures and push again. Use right after opening or updating a PR, or when told CI is red.
---
# CI watch
Babysit the PR's checks so the human only looks at green PRs. Fix the cause of
a failure, never the check.
## 1. Find the PR
```bash
gh pr view --json number,url,headRefName
```
No PR for this branch: stop and say so.
## 2. Watch
```bash
gh pr checks --watch --fail-fast --interval 20
```
CI takes a few minutes, so run this in the background or with a 10 minute
timeout.
| Exit code | Meaning | Next |
| --------- | -------------------------------------- | ----------- |
| 0 | All checks passed | Step 5 |
| 8 | Still pending (the watch was cut off) | Watch again |
| other | A check failed, or none reported yet | Step 3 |
Checks can take up to a minute to appear after a push. If none are reported,
wait 30 seconds and watch again, at most 3 times.
## 3. Read the failure
```bash
gh pr checks --json name,bucket,link --jq '.[] | select(.bucket=="fail")'
gh run view <run-id> --log-failed
```
The run id is the number after /runs/ in the link. For a failed Vercel check,
open the link and read the build log.
Classify before touching code:
| Failure | Action |
| ------------------------------ | ---------------------------------------------------- |
| Lint, format or types | Run `npx vp check` locally, fix, rerun |
| A test | Run that test locally, fix the code or the test's wrong assumption |
| Build or Vercel build | Run `npm run build` locally and fix |
| Codegen out of date | Run `npx convex codegen` and commit the result |
| Runner or network flake | `gh run rerun <run-id> --failed`, once |
| Anything needing a secret or setting | Stop and report. Don't guess |
## 4. Fix and push
1. Reproduce locally first. A fix you can't see pass locally is a guess.
2. Fix the cause in the smallest change that works.
3. Run `npx vp check` and `npx vp test run`.
4. Commit with a message that names the failure, and push.
5. Go back to step 2.
Stop after 3 fix rounds and report what you tried. A fourth attempt in the same
chat is usually going in circles.
## 5. Report
```markdown
## CI: <PR url>
**Result:** green | still failing after N rounds
- Round 1: Tests failed in convex/tasks.test.ts, missing index. Fixed in abc1234.
- Now: Lint, format, types ✓ Tests ✓ Build ✓ Vercel ✓
```
## Never
- Disable, skip or delete a check, test or lint rule.
- Add retries or longer timeouts to get green.
- Edit .github/workflows to change what CI enforces.
- Push with --force or --no-verify.
- Merge the PR.
---
name: orchestrate
description: Plan a change on the main model, then hand the reading and building to cheaper subagents. Use for work that touches several files or splits into independent parts, or when asked to plan and delegate.
---
# Orchestrate
You plan and review. Subagents do the searching and the typing. This keeps the
expensive model on the decisions and keeps this chat's context small, because
subagents only send back summaries.
## Roles
| Role | Who | Model |
| ----------------------------- | ----------------------- | ------------------------------ |
| Plan, split the work, review | You, the main chat | The chat's model, ideally Opus |
| Find code, read logs | `Explore` subagent | haiku |
| Build one piece | `implementer` subagent | sonnet |
## 1. Explore
Send `Explore` subagents with narrow questions, in parallel when they are
unrelated: "where is task state stored", "which screens use Card". Ask for paths
and a short summary, never file dumps.
## 2. Plan
Write the plan before any edit. For each piece:
- the goal in one sentence
- the files it owns
- the check that proves it is done, such as `npx vp test run src/components/features/tasks`
Pieces that touch the same file are one piece. Show the plan and wait for an OK
unless you were told to go ahead.
## 3. Delegate
One `implementer` per piece. Subagents never see this conversation, so every
brief must stand on its own: goal, files it may change, files it must not touch,
the AGENTS.md rules that apply, and the done-when check.
Run pieces in parallel only when their files don't overlap, and at most three at
a time.
## 4. Review
Read every diff yourself, then run `npx vp check` and `npx vp test run`. A piece
that misses its brief goes back once with a precise correction. After a second
miss, fix it yourself.
## 5. Report
Per piece: what changed and who built it. Then what you corrected, and the
checks that passed.
## Never
- Delegate the plan or the final review.
- Give two subagents the same file.
- Send a vague brief like "implement the feature".
- Let a subagent commit, push or open a pull request.
---
name: implementer
description: Builds one well-defined piece of a plan. Use when a brief names the goal, the files to change and the check that must pass.
model: sonnet
---
You build exactly one piece of a larger plan. The brief is all the context you
get, so read it twice.
1. Read AGENTS.md and the files the brief names before editing anything.
2. Change only the files the brief allows. If the work needs another file, stop
and say which one and why.
3. Follow the patterns already in the repo: components from src/components/ui,
Convex functions with argument and return validators, tests next to the code.
4. Run the check the brief names until it passes. After three failed attempts,
stop and report what still fails.
5. Reply with the files you changed, two or three lines on what you did, and the
last lines of the passing check.
Never commit, push, or weaken a test to make a check pass.
---
name: Explore
description: Fast read-only codebase search. Use to find where something lives, how a pattern is used, or what a log says, before planning a change.
tools: Read, Grep, Glob
model: haiku
---
Answer the question you were given by searching the repo. Read only what you
need to answer it.
Reply with the file paths that matter, each with one line on why, then a summary
of at most five lines. Never paste whole files.
Miks Never-loendid on tähtsad. Agent, kellel palutakse CI roheliseks teha, leiab lühima tee ja testi kustutamine on lühike. Iga oskuse lõpus olevad reeglid sulgevad need teed, nii et roheline kontroll tähendab endiselt, et kood töötab.
Leia veel oskusi
9. samm paigaldas viis oskust, mida iga siinne ülesanne vajab. Ülejäänud avaldatakse nagu pakette: üks register, üks käsk ja kaust juhistega, mis maandub sinu repos. See samm näitab, kuidas head oskused üles leida ja kuidas üht hinnata enne, kui see su ekraane muutma hakkab.
Üks register, üks käsk
Iga avaldatud oskus on kirjas lehel skills.sh, järjestatuna selle järgi, mitu projekti selle paigaldas. Sama nimekirja saab otsida ka terminalist: npx skills ei vaja eraldi paigaldust, sest npx tuli 2. sammus koos Node.js-iga.
# Search the registry by keyword. Leave the word off to scroll all of it.
~ % npx skills find vite
# What one repo offers, before any of it lands in your project
~ % npx skills add vercel-labs/agent-skills --list
# What this project and your Mac already have
~ % npx skills list
Paigalda repo sisse, mitte ainult oma Maci. Repos olev oskus jõuab igasse tööruumi ja paistab diffis välja, kus keegi saab selle läbi lugeda. -a claude-code nimetab agendi, nii et käsk ei jää küsima. Jäta globaalne paigaldus nende oskuste jaoks, mida tahad igas projektis, näiteks otsija.
Mida siia juurde tasub lisada
Üheksa oskust, mis sobivad sellega, mille sammud 5 kuni 9 juba ehitasid. Paigalduste arvud muutuvad, nii et vaata enne valimist iga oskuse kõrval olevat praegust numbrit.
| Oskus | Mida see teeb | Kust see tuleb |
|---|---|---|
find-skills | Otsib registrist vestluse seest. Küsi oskust, mis midagi teeb, ja see vaatab enne käsurida edetabelit. Just selle tasub paigaldada globaalselt. | vercel-labs/skills |
web-design-guidelines | Kontrollib ekraani enam kui saja reegli vastu: fookuse järjekord, vormid, liikumine, kiri, kontrast, tume teema ja puutealad. Verceli disainiülevaatus kirja pandud. | vercel-labs/agent-skills |
vercel-react-best-practices | Nelikümmend ja natuke React'i jõudlusreeglit Verceli inseneridelt, järjestatuna selle järgi, kui palju igaüks sulle annab. | vercel-labs/agent-skills |
vercel-composition-patterns | Liitkomponendid ja ülespoole tõstetud olek ühe komponendi asemel, millele on kasvanud üheksa tõeväärtusega atribuuti. | vercel-labs/agent-skills |
vercel-optimize | Loeb Verceli projektist välja raiskamise: vahemälu, funktsioonide suurus ja see, kui tihti need käivituvad. Tasub üle käia, kui eelvaated on juba tihedas kasutuses. | vercel-labs/agent-skills |
shadcn | Käsurearakendus shadcn ja selle register ning see, kuidas komponendid päriselt kokku pannakse. | shadcn-ui/ui |
migrate-radix-to-base | Viib shadcn/ui komponendid Radixilt üle Base UI peale — täpselt see paar, mille 5. samm seadistas. | shadcn-ui/ui |
vite | Arendusserver, kiirlaadimine ja Rolldowni koostamised Vite+ sisemuses. | antfu/skills |
vitest | 8. sammu testijooksutaja, põhjalikumalt kui üks viip mahutada suutis. | antfu/skills |
# The finder, once, for every project on this Mac
~ % npx skills add vercel-labs/skills -s find-skills -a claude-code -g
# Vercel's design and React rules, in this repo
~ % npx skills add vercel-labs/agent-skills -a claude-code \
-s web-design-guidelines -s vercel-react-best-practices
# The toolchain and component library this guide set up
~ % npx skills add shadcn-ui/ui -s shadcn -a claude-code
~ % npx skills add antfu/skills -s vite -s vitest -a claude-code
- Otsija on paigaldatud globaalselt. Ava suvaline tööruum ja küsi oskust, mis teeb midagi, mida sa pole veel ehitanud. Vastuseks peaksid tulema nimed ja paigalduste arvud, mitte oletus.
- Kaks Verceli oskust on repos. Need maanduvad kõrvuti oskustega, mille 6. viip kirjutas, nii et iga siinne tööruum saab need kätte. Tee harus commit ja lase kontrollidel joosta nagu iga teise muudatuse puhul.
- Oled ise ühe SKILL.md läbi lugenud. See on tekst, mida su agent järgib. Kui mõni reegel seal läheb vastuollu AGENTS.md-ga, otsusta kohe, kumb võidab, mitte pärast seda, kui ekraan on ümber kirjutatud.
- Igaühe kohta on rida, mis ütleb, millal see kehtib. Oskus laaditakse kirjelduse järgi, nii et disainioskuste nimetamine pull request'i reeglites säästab sind nende trükkimisest iga ülesande alguses.
Oskus on juhised, mitte sõltuvus. Avaldada saab igaüks ja see, mida paigaldad, on Markdowni fail, mida su agent järgib ilma sinult uuesti küsimata. Jää tuttavate omanike juurde, vaata paigalduste arvu ja loe fail läbi. npx skills remove võtab ühe jälle maha.
Eelvaate taustsüsteemid
Samm 7 annab juba igale pull request'ile oma Convexi taustsüsteemi. See samm muudab eelvaated avamise vääriliseks: need täidetakse näidisandmetega, seadistatakse töölaua väljade asemel repo failidega ja jäetakse vahele, kui PR muudab ainult dokumentatsiooni.
Kõik väärtused, mida need failid loevad, ja teave selle kohta, kas väärtus on salajane, on sammu 7 tabelis.
Viip 7: eelvaate taustsüsteemid
Käivita see pärast viipade 5 ja 6 ühendamist: see koostab dokumentatsioonimalli põhjal juhendi ning lõpetab töö ülevaatusoskustega.
Muuda iga pull request'i Verceli eelvaade avamise vääriliseks: sellele tuleb näidisandmetega Convexi taustsüsteem, mis seadistatakse selle repo failidega. Loe esmalt https://docs.convex.dev/production/hosting/preview-deployments. 1. convex/seed.ts: internalMutation nimega preview koos args- ja returns-valideerijatega, mis lisab tühja tabelisse kolm näidisülesannet. Lisa convex-test'i test, mis käivitab selle kaks korda ja eeldab kolme rida. 2. scripts/vercel-build.sh: käivita npx convex deploy --typecheck disable --cmd-url-env-var-name VITE_CONVEX_URL --cmd 'npm run build' --preview-run 'seed:preview' ning tõrke korral lõpeta sama olekukoodiga. Seejärel käivita ainult eelvaadetes ja nii, et koostamine kunagi ei ebaõnnestuks, npx convex env set --preview-name "$VERCEL_GIT_COMMIT_REF" SITE_URL "https://$VERCEL_BRANCH_URL". 3. scripts/vercel-ignore-build.sh: lõpeta koodiga 0, et koostamine vahele jätta, kui pärast VERCEL_GIT_PREVIOUS_SHA väärtust muutusid ainult docs, *.md, tests, e2e, .github, .claude või .conductor. Lõpeta koodiga 1, et koostada esimesel juurutusel, kui seda commit'i kloonis pole või kui git ebaõnnestub. Ära kasuta ühtegi muud olekukoodi. 4. vercel.json: muuda buildCommand väärtuseks "bash scripts/vercel-build.sh" ja lisa ignoreCommand "bash scripts/vercel-ignore-build.sh". 5. scripts/set-convex-preview-defaults.sh, mis käivitab npx convex env default set APP_ENV preview --type preview --force ja loetleb seejärel eelvaate vaikeväärtused. Käivita see üks kord. 6. CI töö Build: ebaõnnestu, kui convex/_generated on aegunud. Käivita CONVEX_AGENT_MODE=anonymous npx convex dev --once --typecheck disable, seejärel git add convex/_generated ja git diff --cached --exit-code -- convex/_generated. Lõpeta töö sammuga if: always(), mis käivitab pkill -f convex-local-backend || true. 7. Koosta docs/_template.md jaotise Guide põhjal docs/guides/preview-deployments.md, mis sisaldab voo Mermaidi jadadiagrammi ja levinud lõkse. 8. AGENTS.md: ära määra Vercelis kunagi VITE_CONVEX_URL väärtust. Skeemimuudatus, mida olemasolevad andmed ei läbiks, avaldatakse etappidena: esmalt laienda, siis täida andmed ja lõpuks kitsenda. Käivita mõlema skripti jaoks shellcheck ja harus pre-review. Seejärel ava PR oskusega open-pr ning käivita ci-watch.
- Viip 7 töötab uues tööruumis.
- Eelvaate vaikeväärtused on määratud. Agent käivitas
scripts/set-convex-preview-defaults.shsinu sammus 2 kasutatud Convexi sisselogimisega. Convexi töölaual on projekti Settings all nüüd eelvaate juurutuste vaikeväärtusenaAPP_ENV. Vercelisse ei lisata midagi. - Eelvaates on näidisandmed. Ava PR-is Verceli link. Ülesannete loendis kuvatakse kolm lisatud näidisülesannet.
- Taustsüsteem on olemas. Convexi töölaua juurutusmenüüs on selle haru eelvaade.
- Viip 7 on ühendatud. Järgmine juurutus kasutab uut skripti ise ja Vercelis pole vaja midagi muuta.
Eelvaated aeguvad. Convex kustutab eelvaate taustsüsteemi pakettidega Free ja Starter viis päeva pärast selle loomist ning paketiga Professional ja kõrgematel tasemetel 14 päeva pärast. Järgmine üleslükkamine loob uue taustsüsteemi ja täidab selle taas näidisandmetega.
| Sümptom | Põhjus ja lahendus |
|---|---|
| Eelvaates kuvatakse tarbekeskkonna andmeid | VITE_CONVEX_URL on Vercelis määratud ja kirjutab sisestatud URL-i üle. Kustuta see kõigist Verceli keskkondadest ja juuruta uuesti. |
| Uus eelvaate vaikeväärtus puudub sinu harus | Vaikeväärtused jõuavad ainult pärast nende määramist loodud eelvaadetesse. Määra see eelvaates käsuga convex env set --preview-name või lisa väärtuse kirjutamine faili vercel-build.sh. |
| Eelvaates pole ülesandeid | Näidisandmed lisatakse üks kord taustsüsteemi loomisel. Käivita selle juurutuse jaoks Convexi töölaua lehel Functions seed:preview. |
| Koostamine ebaõnnestub skeemiveaga | Olemasolevad dokumendid ei vasta uuele skeemile. Muuda väli valikuliseks, täida olemasolevad andmed ja muuda väli hilisemas PR-is kohustuslikuks. |
| PR-il pole eelvaadet | Muutusid ainult dokumendid, testid või agendi seadistus, seega tühistas vahelejätmise kontroll koostamise. See on ootuspärane; rakenduse järgmine muudatus koostatakse jälle. |
Kaustastruktuur
Alustav rakendus mahub mõnda faili. Kümnenda kuva juures hakkavad agendid arvama, kuhu miski kuulub, ja iga arvamus erineb veidi. Korralda failid tüübi asemel funktsionaalsuse ehk koodi omaniku järgi ning anna agentidele oskus, mis vastab küsimusele „kuhu see läheb?“ iga kord ühtemoodi. Struktuur järgib sama tehnoloogiakomplektiga loodud tootmisrepo eeskuju.
my-app
├── src/
│ ├── components/
│ │ ├── ui/ ainult shadcn, lisatud CLI-ga
│ │ ├── layout/ rakenduse kest, päis ja navigeerimine
│ │ ├── common/ kasutajaliides, mida jagab vähemalt kaks funktsiooni
│ │ └── features/
│ │ ├── tasks/ task-list.tsx, use-tasks.ts ja nende testid
│ │ └── settings/ üks kaust iga funktsiooni kohta
│ ├── hooks/ konksud, mis ei kuulu ühele funktsioonile
│ ├── lib/ kasutajaliideseta pakkujad ja abifunktsioonid
│ └── main.tsx
├── convex/
│ ├── schema.ts koondab ainult iga domeeni tabelid
│ ├── test.setup.ts moodulite loend convex-testile
│ ├── tasks/
│ │ ├── schema.ts tasksTables
│ │ ├── controller.ts list, create, toggle
│ │ ├── controller.test.ts
│ │ └── seed.ts eelvaadete näidisandmed
│ ├── lib/ jagatud abifunktsioonid nimega *.lib.ts
│ └── _generated/ genereeritud, commit'itud
└── docs/ e2e/ scripts/
| Lisad | Asukoht |
|---|---|
| Kuva, selle oleku või hook'id | src/components/features/<feature>/, testid selle kõrval |
| Midagi, mida vajab teine funktsionaalsus | common/, hooks/ või lib/, kuid alles siis, kui teine funktsionaalsus on olemas |
| shadcn-i komponendi | src/components/ui/, shadcn-i CLI kaudu |
| Convexi päringu või mutatsiooni | convex/<domain>/controller.ts, nimega list või create, sest kausta nimi ütleb juba tasks |
| Convexi tabeli | convex/<domain>/schema.ts, mis laotatakse juurkausta faili schema.ts |
| Convexi abifunktsiooni | Fail *.lib.ts. Convex jätab kahe punktiga failinimed vahele, seega ei muutu abifunktsioonid kunagi avalikeks funktsioonideks |
Miks funktsionaalsuse järgi. Kui kõik ülesannetega seotu asub ühes kaustas, loeb ülesandeid muutev agent ühte kausta, ümbernimetamisel liigub test koos failiga ja eri funktsionaalsustega tegelevad tööruumid puudutavad harva samu faile. Tüübi järgi kaustad, näiteks üks suur hooks/ või utils/, hajutavad iga funktsionaalsuse üle kogu repo.
Viip 8: korralda funktsionaalsuse järgi
Failide teisaldamine tekitab kõigega konflikte, seega käivita see siis, kui üheski teises tööruumis pole pooleliolevat tööd. Viiba kopeerimisel lisatakse allolev oskus. Convexi samme on katsetatud: funktsioonide teisaldamisel valdkonnakaustadesse jäävad testid roheliseks, kui nad jagavad ühte mooduliloendit.
Korralda see repo funktsionaalsuse järgi ümber, et igal failil oleks ilmselge asukoht. Selle viiba alla on kleebitud oskus folder-structure. Ainult teisaldamised, käitumist ei muudeta. 1. Salvesta oskus failina .agents/skills/folder-structure/SKILL.md, lingi see kausta .claude/skills ja kontrolli selle teid selle repo järgi. 2. Kasutajaliides: src/components/ui jääb ainult shadcn-i jaoks. Teisalda iga kuva koos selle hook'ide ja testidega kausta src/components/features/<feature>/ (esimesena tasks), rakenduse kest kausta src/components/layout/ ning kasutajaliideseta abifunktsioonid kausta src/lib/. 3. Convex: üks kaust iga valdkonna kohta. convex/tasks/schema.ts ekspordib tasksTables, convex/tasks/controller.ts sisaldab funktsioone ning convex/schema.ts laotab ainult iga valdkonna tabelid. Teisalda näidisandmete skript faili convex/tasks/seed.ts ja muuda faili scripts/vercel-build.sh väärtus --preview-run kujule 'tasks/seed:preview'. 4. Convexi testid: lisa convex/test.setup.ts reaga export const modules = import.meta.glob("./**/*.ts") ja impordi sellest modules igasse testi. Alamkaustas olev glob ei leia väljaspool seda asuvaid mooduleid. 5. Uuenda kõiki importe ja api-teid: api.tasks.list asemel tuleb api.tasks.controller.list. Kasuta kaustade vahel aliast @/. Ära kasuta index.ts koondfaile. 6. Koosta docs/_template.md jaotise Architecture põhjal docs/architecture/folder-structure.md: failipuu, iga kausta vastutus ja uute failide asukohad. 7. AGENTS.md: üks rida, mis ütleb, et uued failid järgivad oskust folder-structure. Käivita npx convex codegen ja seejärel pre-review. Töö on valmis, kui vp check, vp test ja npm run build õnnestuvad. Ava PR oskusega open-pr ning käivita ci-watch.
- Teised tööruumid on ühendatud või arhiivitud enne viiba 8 käivitamist.
- Viip 8 töötab.
- Diff koosneb peamiselt ümbernimetamistest. Diff'i vaates kuvatakse teisaldatud faile ümbernimetatud, mitte kustutatud ja uuesti loodud failidena. Iga ümber kirjutatud faili kohta tasub vestluses küsida.
- Eelvaates on endiselt näidisandmed. See tõendab, et faili
vercel-build.shuus näidisandmete tee töötab. - Viip 8 on ühendatud. Uus funktsionaalsus algab nüüd kaustaga kataloogis
features/.
---
name: folder-structure
description: Decide where new code goes and keep the repo organized by feature. Use when creating a file, screen, component, hook, Convex function or table, or when moving code between folders.
---
# Folder structure
Code is organized by who owns it, not by what kind of file it is. Read
docs/architecture/folder-structure.md for the reasons; this skill is the
checklist.
## Where things go
| You are adding | It goes | Notes |
| --------------------------------------- | ----------------------------------------- | -------------------------------------------------- |
| A screen, its state or a feature hook | `src/components/features/<feature>/` | Tests and styles sit beside it |
| The app shell, header or navigation | `src/components/layout/` | Shell-wide wiring only |
| UI two or more features use | `src/components/common/` | Not a second design system |
| A shadcn/ui component | `src/components/ui/` | Only through the shadcn CLI. Never hand-written |
| A hook with no single owner | `src/hooks/` | A feature's own hooks stay in the feature |
| Logic, providers or helpers with no UI | `src/lib/` | Use `src/lib/<feature>/` if one feature owns it |
| A Convex query, mutation or action | `convex/<domain>/controller.ts` | Export `list`, `create`, not `listTasks` |
| A Convex table | `convex/<domain>/schema.ts` | Export `<domain>Tables`; root `schema.ts` spreads it |
| A Convex helper | `convex/<domain>/*.lib.ts` or `convex/lib/` | The second dot keeps it out of the public API |
| Sample data for previews | `convex/<domain>/seed.ts` | Run by `--preview-run` in `scripts/vercel-build.sh` |
| A test | Next to the file, as `name.test.ts(x)` | No separate tests folder |
| A doc | `docs/<type>/` | Start from `docs/_template.md` |
| A script | `scripts/<name>.sh` or `.ts` | One purpose per file |
## Naming
- Files and folders are kebab-case: `task-row.tsx`, `use-task-filter.ts`.
- A feature folder and its Convex domain share a name: `features/tasks` and `convex/tasks`.
- Hooks start with `use-`. Tests end in `.test.ts` or `.test.tsx`.
## Rules
1. **Start inside the feature.** Code moves to `common/`, `hooks/` or `lib/`
when a second feature actually needs it, not in case one might.
2. **Import from the file that declares it.** Use the `@/` alias across
folders and relative paths inside one. No `index.ts` barrels, no re-exports.
3. **Nothing points back up.** `components/ui` never imports from `features`,
and `convex/` never imports from `src/`.
4. **A move is its own change.** Moving files and changing behaviour in the same
PR hides the real diff. Move first, merge, then change.
5. **Moving a Convex function changes its path.** `convex/tasks.ts` exporting
`list` is `api.tasks.list`; in `convex/tasks/controller.ts` it becomes
`api.tasks.controller.list`. Update every caller, the tests, and any
`--preview-run` path, then run `npx convex codegen`.
## Before you finish
- Every new file matches a row in the table. If none fits, stop and ask, then
add the row to docs/architecture/folder-structure.md in the same PR.
- `npx vp check`, `npx vp test run` and `npm run build` pass.
- The diff shows moved files as renames, not as deletes plus new files.
## Never
- Put feature code in `src/components/ui`.
- Create `utils/`, `helpers/` or `misc/` folders. Name the folder for what it owns.
- Add an `index.ts` that only re-exports.
- Move files while other workspaces have open PRs that touch them.
Convexi komponendid
Komponent on valmis taustsüsteemifunktsioon, mille paigaldad npm-ist. Sellega tulevad sinu omade kõrval liivakastis töötavad tabelid ja funktsioonid ning sinu kood kasutab neid components.<name> kaudu. Enne oma sisselogimise, e-posti järjekorra või AI-vestluse loomist vaata komponentide kataloogi. Iga ametliku komponendiga avaldatakse ka koodiagentidele kirjutatud SKILL.md, millele allolevad viibad viitavad.
- Paigalda see npm-iga nagu iga teine pakett.
- Registreeri see failis
convex/convex.config.ts. Kõik komponendid on kirjas ühes failis ja sama komponendi võib registreerida kaks korda eri nimedega. - Genereeri tüübid. Käivitusskriptis olev
npx convex devteeb seda jacomponents.<name>ilmub sinu koodi. - Kasuta selle klienti, näiteks
new Resend(components.resend), oma päringutes, mutatsioonides ja toimingutes, kus kehtivad endiselt sinu juurdepääsukontrollid.
| Komponent | Mida see annab | Võtmed |
|---|---|---|
| Sisselogimine | ||
| Kontod, seansid, e-post ja parool, sotsiaalkontodega sisselogimine, kaheastmeline autentimine | BETTER_AUTH_SECRET, SITE_URL | |
| E-post | ||
| Järjekorda ja partiidesse koondatud e-kirjad, mis saadetakse täpselt üks kord, koos kohaletoimetamise ja tagasipõrgete veebihaakidega | RESEND_API_KEY, RESEND_WEBHOOK_SECRET | |
| Taustatöö | ||
| Eraldi järjekorrad paralleeltöö piiranguga, viivitusega korduskatsed ja lõpetamise tagasikutsed | Pole vaja | |
| Mitmeastmelised tööd, mis jätkuvad pärast taaskäivitust ja võivad päevi oodata | Pole vaja | |
| AI | ||
| AI-assistentide vestluslõimed, sõnumiajalugu, tööriistad ja voogedastus | AI Gateway kasutamisel pole vaja, muidu teenusepakkuja võti | |
| Sinu sisu otsing, et agent vastaks selle põhjal | Sama mis Agentil | |
| Kuritarvitamise kaitse | ||
| Kasutajapõhised või globaalsed piirangud, mis võetakse koos mutatsiooniga tagasi | Pole vaja | |
| Maksed | ||
| Kassavoog, tellimused ja kliendiportaal, mis sünkroonitakse Convexisse | POLAR_ORGANIZATION_TOKEN, POLAR_WEBHOOK_SECRET | |
| Kassaseansid, tellimused ja arved, mis sünkroonitakse veebihaagiga | STRIPE_SECRET_KEY, STRIPE_WEBHOOK_SECRET | |
| Reaalajas | ||
| Reacti konksuga näed, kes parasjagu ruumis viibib | Pole vaja | |
| Andmed | ||
| Olemasolevate dokumentide muutmine jätkatavate partiidena | Pole vaja | |
| Koguarvud, summad ja pingeread ilma terveid tabeleid läbi vaatamata | Pole vaja | |
Sisseehitatud, komponenti pole vaja. Failihoidla, ajastatud funktsioonid, cron-tööd failis convex/crons.ts, teksti- ja vektorotsing ning HTTP-lõpp-punktid kuuluvad iga Convexi juurutuse juurde.
Levinud funktsioonid
Enamik rakendusi vajab samu põhifunktsioone. Iga allolev viip on mõeldud ühe tööruumi ja ühe PR-i jaoks ning palub agendil esmalt komponendi enda juhiseid lugeda. Alusta sisselogimisest, sest peaaegu kõik muu kontrollib kasutaja isikut.
Võtmed ei jõua vestlustesse. Kui funktsioon vajab Resendi, Polari või AI-teenusepakkuja võtit, palub viip agendil öelda, kuhu see Convexi juhtpaneelil lisada. Kleebi see ise õigesse juurutusse, järgides 7. sammu tabelit.
Sisselogimine ja kontod
Better Auth töötab sinu Convexi taustsüsteemis, seega asuvad kasutajakontod sinu andmete kõrval ja eraldi autentimisteenust pole vaja. Viip ühendab Convexi juhendi Vite SPA seadistuse ning lisab iga saladuse õigesse juurutusse.
Lisa kontod Convexi Better Auth komponendiga. Loe esmalt https://www.convex.dev/components/better-auth/SKILL.md ja aadressil https://labs.convex.dev/better-auth/framework-guides/react olev Reacti (Vite SPA) juhend läbi ning järgi neid täpselt. Kontrolli iga API-t kehtiva dokumentatsiooni põhjal Context7 abil, mitte mälu järgi. 1. Paigalda @convex-dev/better-auth ja juhendis kinnitatud better-auth versioon. Registreeri komponent failis convex/convex.config.ts, seejärel lisa convex/auth.config.ts, convex/auth.ts koos crossDomain- ja convex-lisanditega, cors-iga marsruudid failis convex/http.ts ning src/lib/auth-client.ts, ja ümbritse rakendus ConvexBetterAuthProvideriga. 2. Loo e-posti ja parooliga registreerimise, sisselogimise ning väljalogimise vaated src/components/ui komponentidest koos laadimis- ja veaolekutega. 3. Iga avalik Convexi funktsioon, mis puudutab kasutaja andmeid, kontrollib esmalt sisselogitud kasutajat ja viskab vea, kui teda pole. Ülesanded saavad välja userId ja indeksi ning iga kasutaja näeb ainult enda omi. 4. Keskkonnaväärtused, igaüks õiges juurutuses: Dev: määra BETTER_AUTH_SECRET arendusjuurutuste projekti vaikeväärtuseks käsuga npx convex env default set --type dev ainult siis, kui seda pole veel määratud, ning lisa see ka selle tööruumi juurutusse. Lisa käsk npx convex env set SITE_URL http://localhost:$CONDUCTOR_PORT Conductor setup scripti. Preview: lisa BETTER_AUTH_SECRET faili scripts/set-convex-preview-defaults.sh; see genereeritakse ainult puudumise korral ja seda ei vahetata kunagi. vercel-build.sh määrab juba iga eelvaate SITE_URL-i. Production: määra failis vercel-build.sh ainult tarbekeskkonnas ja võimaluse korral SITE_URL väärtusest VERCEL_PROJECT_PRODUCTION_URL. Määra BETTER_AUTH_SECRET tarbekeskkonnas ühe korra käsuga npx convex env set --prod, kasutades uut juhuslikku väärtust. 5. Lisa BETTER_AUTH_SECRET ja SITE_URL faili AGENTS.md env-jaotisse koos infoga, kus kumbki asub. Kasuta oskust orchestrate. Pane Convexi kood kataloogi convex/auth/ ja vaated kataloogi src/components/features/auth/, järgides oskust folder-structure. Lisa juurdepääsukontrollidele convex-test testid ja dokument faili docs/_template.md jaotisest Integration. Käivita pre-review, ava oskusega open-pr PR ja seejärel käivita ci-watch.
E-kirjad
Resend paneb saatmised Workpooli kaudu järjekorda, proovib neid uuesti ja tagab, et iga e-kiri läheb välja ühe korra. Testrežiim on vaikimisi sisse lülitatud, seega ei saa arendus- ega eelvaatekeskkond päris kliendile kirja saata.
Lisa tehingulised e-kirjad Convexi Resend komponendiga. Loe esmalt https://www.convex.dev/components/resend/SKILL.md ja selle README läbi ning järgi neid täpselt. Kontrolli iga API-t kehtiva dokumentatsiooni põhjal Context7 abil, mitte mälu järgi. 1. Paigalda @convex-dev/resend, registreeri see failis convex/convex.config.ts ja loo üks Resend eksemplar failis convex/email/resend.ts. testMode jääb väärtusele true, välja arvatud juhul, kui APP_ENV on "production". 2. Loo igale e-kirja tüübile sisemine mutatsioon, alustades tervituskirjast. Kasuta failis convex/email/templates.ts lihtsaid HTML-malle rakenduse nime ja värvidega. 3. Kui Better Auth on paigaldatud, saada selle kinnitamis- ja parooli lähtestamise kirjad selle komponendi kaudu. 4. Ühenda Resendi veebihaak failis convex/http.ts teele /resend-webhook ning salvesta onEmailEvent abil delivered-, bounced- ja complained-sündmused. 5. Võtmed lähevad ainult tarbekeskkonda: RESEND_API_KEY, RESEND_WEBHOOK_SECRET ja APP_ENV=production. Dev ja eelvaated jäävad testrežiimi ning saadavad aadressile delivered@resend.dev. Ütle mulle täpselt, millised väärtused pean tarbekeskkonna jaoks Convexi juhtpaneelile lisama, kust need Resendis leida ja milline veebihaagi URL sinna kleepida. Ära palu mul võtmeid siia vestlusse kleepida. 6. Saatja aadress kasutab Resendis kinnitatud domeeni. Küsi minult, millist. Pane Convexi kood kataloogi convex/email/ ja vaated kataloogi src/components/features/settings/, järgides oskust folder-structure. Lisa juurdepääsukontrollidele convex-test testid ja dokument faili docs/_template.md jaotisest Integration. Käivita pre-review, ava oskusega open-pr PR ja seejärel käivita ci-watch.
Taustatööd
Workpool hoiab kiireloomulised tööd, näiteks e-kirjad, hulgitööde taha ootama jäämast. Workflow sobib mitme sammu või pikkade ooteaegadega protsessidele, mis peavad lõpuni jõudma ka siis, kui mõni samm ebaõnnestub.
Eemalda aeglane või korduskatseid vajav töö päringu teelt. Loe esmalt https://www.convex.dev/components/workpool/workpool.md ja https://www.convex.dev/components/workflow/SKILL.md läbi ning järgi neid täpselt. Kontrolli iga API-t kehtiva dokumentatsiooni põhjal Context7 abil, mitte mälu järgi.
1. Paigalda @convex-dev/workpool. Registreeri failis convex/convex.config.ts kaks nimega kogumit: emailWorkpool väärtusega maxParallelism 10 ja backgroundWorkpool väärtusega maxParallelism 3.
2. Kõik mutatsioonist välise API kutsed käivad ctx.scheduler.runAfter asemel läbi pool.enqueueAction. Lülita korduskatsed sisse ainult toimingutel, mida on ohutu korrata, ning salvesta ebaõnnestumised onComplete-käsitlejas.
3. Protsessi [the multi-step process] jaoks paigalda @convex-dev/workflow ja määratle see töövoona, mille sammud on sisemised funktsioonid. Näita selle edenemist kasutajaliideses töövoo olekut päriva päringuga.
4. Kindla ajakava alusel käivad tööd lähevad faili convex/crons.ts, mis ei vaja komponenti.
5. Dokumenteeri failis docs/architecture/background-jobs.md, millist kogumit iga töö kasutab ja miks.
Lisa testid töid järjekorda panevatele mutatsioonidele. Käivita pre-review, ava oskusega open-pr PR ja seejärel käivita ci-watch.
AI-assistent
Agent salvestab vestlused Convexis lõimedena ja voogedastab vastused sama reaalajaühenduse kaudu nagu ülejäänud andmed. Tasuliste pakettidega beetaversioonis saadaval olev Convex AI Gateway eemaldab vajaduse teenusepakkuja võtme järele täielikult.
Lisa AI-assistent Convexi Agent komponendiga. Loe esmalt https://www.convex.dev/components/agent/SKILL.md ja https://docs.convex.dev/agents läbi ning järgi neid täpselt. Kontrolli iga API-t kehtiva dokumentatsiooni põhjal Context7 abil, mitte mälu järgi. 1. Paigalda @convex-dev/agent, registreeri see ja määratle failis convex/assistant/agent.ts üks agent lühikeste juhiste ning ainult vajalike tööriistadega. 2. Juurdepääs mudelile: küsi minult, kas meie Convexi tiimil on tasuline pakett. Kui jah, kasuta Convex AI Gatewayd koos paketiga @convex-dev/ai-sdk-provider (https://docs.convex.dev/ai-gateway/overview), et võtit poleks vaja. Kui ei, kasuta teenusepakkuja AI SDK paketti, mille võti on salvestatud Convexi keskkonnamuutujana: projekti vaikeväärtus arendus- ja eelvaatejuurutustele, lisaks selle tööruumi juurutus ning eraldi väärtus tarbekeskkonnas. Ütle mulle täpselt, mida kuhu lisada. 3. Lõimed kuuluvad kasutajatele. Loo iga vestluse jaoks üks lõim, kontrolli igas funktsioonis omanikku ja loetle kasutaja lõimed päringuga. 4. Voogedasta vastused lõimeloendiga vestlusvaatesse, mis on loodud src/components/ui komponentidest ning sisaldab laadimis-, tühja ja veaolekut. 5. Piira kasutaja sõnumeid paketiga @convex-dev/rate-limiter (lubade ämber, 10 minutis) ja näita, millal ta saab uuesti saata. 6. Ära kutsu testides kunagi päris mudelit. Asenda keelemudel imitatsiooniga. Kasuta oskust orchestrate. Pane Convexi kood kataloogi convex/assistant/ ja vaated kataloogi src/components/features/assistant/, järgides oskust folder-structure. Lisa juurdepääsukontrollidele convex-test testid ja dokument faili docs/_template.md jaotisest Integration. Käivita pre-review, ava oskusega open-pr PR ja seejärel käivita ci-watch.
Sageduspiirangud
Piiranguid kontrollitakse kirjutamisega samas tehingus, seega ei jäta blokeeritud päring midagi maha.
Kaitse toiminguid [sign-in attempts, invites, uploads] Convexi Rate Limiter komponendiga. Loe esmalt https://www.convex.dev/components/rate-limiter/SKILL.md läbi ja järgi seda täpselt. Kontrolli iga API-t kehtiva dokumentatsiooni põhjal Context7 abil, mitte mälu järgi.
1. Paigalda @convex-dev/rate-limiter, registreeri see ja määratle kõik piirangud ühes kohas, failis convex/rateLimits.ts, lisades kommentaari selle kohta, miks iga arv valiti.
2. Kasuta sagedate toimingute jaoks token bucket'it ja päevapiirangute jaoks fixed window'd. Võtmesta kasutaja toimingud kasutaja ID ning anonüümsed toimingud seansi ID järgi, mitte kunagi ilma võtmeta.
3. Kutsu tööd tegevas mutatsioonis välja limit koos throws-iga, et blokeeritud päring ei kirjutaks midagi.
4. Keela toiming kasutajaliideses ja näita komponendi Reacti konksu abil, millal see jälle saadaval on.
Lisa testid, mis ammendavad iga piirangu ja tõestavad kirjutamise tagasivõtmist. Käivita pre-review, ava oskusega open-pr PR ja seejärel käivita ci-watch.
Failide üleslaadimine
Failihoidla kuulub iga Convexi juurutuse juurde. Failid laaditakse otse hoidlasse ja sinu dokumendid säilitavad ainult hoidla ID.
Lisa [avatar or attachment] üleslaadimine Convexi failihoidlaga, mis on sisseehitatud ega vaja komponenti. Loe esmalt https://docs.convex.dev/file-storage/upload-files.
1. Loo mutatsioon generateUploadUrl, mis kontrollib enne URL-i tagastamist sisselogitud kasutajat.
2. Klient postitab faili sellele URL-ile ja salvestab seejärel storageId mutatsiooniga, mille valideerija on v.id("_storage").
3. Loe salvestamisel faili metaandmeid ja lükka tagasi kõik, mis pole pilt või on suurem kui 5 MB, ning kustuta salvestatud fail.
4. Tagasta dokumenti väljastavas päringus URL funktsioonist ctx.storage.getUrl. Ära salvesta kunagi URL-e.
5. Kui fail asendatakse või selle omanik kustutatakse, kustuta vana fail.
6. Loo src/components/ui komponentidest üleslaadimise juhtelement koos eelvaate, üleslaadimise ajaks keelatud oleku ja selgete veateadetega.
Pane Convexi kood kataloogi convex/files/ ja vaated kataloogi src/components/features/files/, järgides oskust folder-structure. Lisa juurdepääsukontrollidele convex-test testid ja dokument faili docs/_template.md jaotisest Integration. Käivita pre-review, ava oskusega open-pr PR ja seejärel käivita ci-watch.
Maksed
Mõlemad komponendid sünkroonivad kliendid ja tellimused veebihaakide kaudu Convexi tabelitesse, seega saab paketti kontrollida tavalise päringuga.
Lisa tasulised paketid Convexi Polar komponendiga. Polar on ametlik müüja, seega tegeleb see müügimaksuga. Loe esmalt https://www.convex.dev/components/polar/SKILL.md ja selle README läbi ning järgi neid täpselt. Kontrolli iga API-t kehtiva dokumentatsiooni põhjal Context7 abil, mitte mälu järgi. 1. Paigalda @convex-dev/polar, registreeri see ja seadista tooted failis convex/billing/polar.ts, lugedes toote ID-d keskkonnamuutujatest. 2. Registreeri Polari veebihaagi marsruudid failis convex/http.ts. 3. Kasuta kõikjal peale tarbekeskkonna testkeskkonda: POLAR_SERVER=sandbox koos testkeskkonna tokenitega arendus- ja eelvaatejuurutuste projekti vaikeväärtustena, päris tokenid ja POLAR_SERVER=production ainult tarbekeskkonnas. Vaikeväärtused jõuavad ainult pärast nende määramist loodud juurutustesse, seega määra testkeskkonna väärtused ka selle tööruumi juurutuses. 4. Kontrolli tellimust Convexi funktsioonides enne iga tasulist toimingut. Nupu peitmisest ei piisa. 5. Loo hinnastuse ja arvelduse vaated koos kassavoo ning kliendiportaali lingiga. 6. Ütle mulle täpselt, millised väärtused pean Convexi juhtpaneelile iga juurutuse tüübi jaoks lisama ning millise veebihaagi URL-i Polarisse kleepima. Ära palu mul võtmeid siia vestlusse kleepida. Kui vajame selle asemel Stripe'i, kasuta https://www.convex.dev/components/stripe/SKILL.md sama keskkonnajaotusega: Stripe'i testrežiimi STRIPE_SECRET_KEY ja STRIPE_WEBHOOK_SECRET arendus- ja eelvaatejuurutuste projekti vaikeväärtustena ning päris väärtused ainult tarbekeskkonnas. Pane Convexi kood kataloogi convex/billing/ ja vaated kataloogi src/components/features/billing/, järgides oskust folder-structure. Lisa juurdepääsukontrollidele convex-test testid ja dokument faili docs/_template.md jaotisest Integration. Käivita pre-review, ava oskusega open-pr PR ja seejärel käivita ci-watch.
Kes on võrgus
Presence saadab uuenduse ainult siis, kui keegi ruumiga liitub või sealt lahkub, mitte iga südamelöögi ajal.
Näita Convexi Presence komponendiga, kes veel vaatab [a page or document]. Loe esmalt https://www.convex.dev/components/presence/SKILL.md ja selle README läbi ning järgi neid täpselt. Kontrolli iga API-t kehtiva dokumentatsiooni põhjal Context7 abil, mitte mälu järgi.
1. Paigalda @convex-dev/presence, registreeri see ning tee heartbeat, list ja disconnect failis convex/presence.ts kättesaadavaks. Kõik kolm kontrollivad sisselogitud kasutajat ning kasutaja ID tuleb seansist, mitte kunagi kliendilt.
2. Kasuta konksu usePresence, määrates ruumiks lehe või dokumendi ID.
3. Loo shadcn Avatarist väike avatarivirn, kus igal nimel on kohtspikker ja ülejääki näitab "+3".
Pane Convexi kood kataloogi convex/presence/ ja vaated kataloogi src/components/features/presence/, järgides oskust folder-structure. Lisa juurdepääsukontrollidele convex-test testid ja dokument faili docs/_template.md jaotisest Integration. Käivita pre-review, ava oskusega open-pr PR ja seejärel käivita ci-watch.
Keeled
Paraglide kompileerib sõnumifailid tüübitud funktsioonideks, nii et tõlkimata jäänud tekst katkestab koostamise, selle asemel et jõuda eestikeelsele ekraanile inglise keeles. Tee seda varakult: sadade tekstide hilisem komponentidest välja tõstmine on selle töö kallis versioon.
Lisa Paraglide JS-iga mitme keele tugi. Loe esmalt https://paraglidejs.com läbi ning järgi seda täpselt. Kontrolli iga API-t kehtiva dokumentatsiooni põhjal Context7 abil, mitte mälu järgi. Keeled, mida soovin, on [English and Estonian]. 1. Paigalda kompilaator käsuga pnpm add @inlang/paraglide-js, seejärel loo fail project.inlang/settings.json, kus baseLocale on "en" ja igal keelel on oma kirje. Suuna sõnumivormingu pistikprogramm teele ./messages/{locale}.json, lisa faili vite.config.ts paraglideVitePlugin, mille outdir on ./src/paraglide, ning lisa see kaust gitignore'i, sest see luuakse igal koostamisel uuesti. 2. Tõsta kõik kasutajale nähtavad tekstid faili messages/en.json ja loo igale teisele keelele täpselt samade võtmetega fail. Nimeta võtmed kujul domain_descriptor snake_case-vormingus, näiteks common_save ja nav_settings, ning hoia jagatud sõnad common_ all, et need tõlgitaks ühe korra. 3. Asenda komponentides olevad tekstid impordiga import * as m from "@/paraglide/messages.js" ja kutsu neid kujul m.common_save(). Sõnumifunktsioonid käivituvad renderdamise ajal, seega tuleb mooduli tasemel konstant, mis mõnda neist hoiab, muuta funktsiooniks. 4. Sea strateegiaks url, siis cookie, siis baseLocale, et keel oleks aadressiribal näha ja püsiks ka pärast lehe uuesti laadimist, ning lisa valija, mis kutsub setLocale. 5. Kuupäevad ja arvud järgivad rakenduse keelt, mitte brauseri oma. Pane iga Intl-i kutse ühe abifunktsiooni taha, mis võtab aktiivse keele, ja ära kunagi kutsu toLocaleDateString ilma argumendita. 6. Lisa kontroll, mis ebaõnnestub, kui võti on olemas ühes sõnumifailis, aga mitte teises, ja käivita see CI-s teiste kontrollide kõrval. Iga järgmise teksti puhul: jäta kohatäited täpselt samaks, ära tõlgi brändinimesid ega identifikaatoreid ning kirjuta terve lause ühe parameetritega sõnumina, selle asemel et ühendada kaks kutset malliliteraaliga, sest sõnajärg on keeleti erinev. Pane sõnumifailid kataloogi messages/ ja keeleabifunktsioonid kataloogi src/lib/i18n/, järgides oskust folder-structure. Testid kontrollivad m.key() kaudu, mitte kopeeritud tõlke järgi, nii et ümbertõlkimine neid kunagi ei lõhu. Lisa dokument faili docs/_template.md jaotisest Integration. Käivita pre-review, ava oskusega open-pr PR ja seejärel käivita ci-watch.
Tõlge on ka paigutuse muudatus. Eesti ja läti keel on lühikestel siltidel inglise keelest 30–50% pikemad, nii et nupp, mis inglise keeles ära mahub, võib tõlkes katki minna. Vaata iga uus keel enne ühendamist üle telefoni laiuses.
Töötsükkel
Kui seadistus on tehtud, läbib iga muudatus samad sammud. Nädala pärast ei tundugi need enam eraldi sammudena.
- Jaga töö osadeks. Loo eraldi tööruum iga asja jaoks, mille saab iseseisvalt avaldada: vaade, viga või tekstiparandus.
- Uus tööruum ⌘N Võid selle alustada ka GitHubi või Lineari ülesandest, harust või PR-ist. Esmalt käivitub seadistusskript.
- Kirjuta viip. Kui muudatus on suurem kui pisiparandus, lülita klahvidega ⇧Tab sisse plaanirežiim ja kiida plaan enne muudatuste tegemist heaks.
- Käivita rakendus ⌘R Avab rakenduse selle tööruumi pordil. Proovi see kasutajana läbi.
- Vaata erinevused üle ⌘⇧D Kommenteeri ridu ja saada kommentaarid agendile. Käivita kontroll ⌘⇧R, et saada uuelt agendilt teine arvamus.
- Eelkontroll. Sisesta
/pre-review. Paranda kõik blokeerivad vead enne, kui keegi teine muudatust vaatab. - Loo PR ⌘⇧P Agent järgib oskust open-pr: pealkiri, mall ja kuvatõmmised. Seejärel sisesta
/ci-watchja lase agendil kontrollid korda teha. - Vaata vahekaarti Checks. Seal on koos Giti olek, CI-tööd, juurutused, ülevaatuse kommentaarid ja ülesanded. Ava Verceli eelvaate link ja testi seal eraldi näidisandmetega taustsüsteemi.
- Ühenda ⌘⇧M Tööruum arhiveerib end ise. Vajaduse korral taasta see jaotisest History.
Proovi: kolm agenti korraga
Loo kolm tööruumi ja kleebi igasse üks ülesanne. Need puudutavad rakenduse eri osi, seega saavad agendid töötada paralleelselt.
Tööruum 1 · andmed
Tööruum 2 · uus vaade
Tööruum 3 · väike funktsioon
Kui kaks PR-i muudavad sama faili, võib teisel tekkida ühendamiskonflikt. See on normaalne. Conductoris on toiming, mis palub agendil selle lahendada.
| Kiirklahv | Toiming Conductoris |
|---|---|
| ⌘N | Uus tööruum |
| ⌘R | Käivita või peata käivitusskript |
| ⌘J | Näita või peida terminalipaneel |
| ⇧Tab | Lülita vestluses plaanirežiimi |
| ⌘U | Lisa manus, näiteks kuvatõmmis |
| ⌘⇧D | Ava erinevuste vaade |
| ⌘⇧R | Alusta ülevaatust |
| ⌘⇧P | Loo PR |
| ⌘⇧L | Tõmba haru main uusimad muudatused |
| ⌘⇧M | Ühenda PR |
| ⌘⇧A | Arhiveeri tööruum |
Hea ülesande kirjutamine
Suhtu agenti nagu võimekasse koostööpartnerisse tema esimesel tööpäeval. Ta suudab peaaegu kõike, kuid ei loe sinu mõtteid. Heal viibal on neli osa.
| Osa | Näide |
|---|---|
| Eesmärk | Rühmita seadete väljad profiiliks ja teavitusteks. |
| Asukoht | Seadete leht. Kasuta src/components/ui komponenti shadcn Card. |
| Reeglid | Säilita olemasolevad väljad. Võta vahed CSS-i muutujatest. |
| Valmis, kui | vp check õnnestub ja leht püsib korras 375px laiusel. |
vp check õnnestub ja paigutus püsib korras 375px laiusel.- Anna kontroll, mida agent saab käivitada. Anthropici järgi eristab see seanssi, mida pead jälgima, seansist, mille juurest võid lahkuda. Koostamiskäsk, lint-käsk või test: mis tahes kontroll, mis kas õnnestub või ebaõnnestub.
- Näita, ära kirjelda. Lisa klahvidega ⌘U kuvatõmmis või Figma eksport ja palu agendil loetleda erinevused.
- Lisa teadaolevad lõksud viipa. 1. viip nimetas teadaolevad Vite+ probleemid kohe. Kui sama lõks ilmub kaks korda, lisa see faili AGENTS.md.
- Kaks eksimust, uus vestlus. Kui oled sama viga kaks korda parandanud, on vestlus täis ebaõnnestunud katseid. Alusta uuesti parema esimese sõnumiga.
Korduskasutatavad viibad
Kopeeri sobiv viip, täida esiletõstetud osad ja saada see. Igaüks töötab kõige paremini eraldi tööruumis.
Loo kujunduse põhjal vaade
Mõista enne muutmist
Plaani suuremat tööd
Paranda viga korralikult
Haru kujundusülevaatus
Õpeta agenti pärast viga
Muuda harjumus oskuseks
Võta ühendatud muudatus tagasi
Kui midagi läheb katki
Enamasti kleebi viga tööruumi vestlusse ja palu agendil see parandada. Tabel aitab mõista, mis toimub.
| Mida näed | Mis toimub |
|---|---|
| Conductor ütleb, et GitHub pole ühendatud | Käivita terminalis uuesti gh auth login ja taaskäivita Conductor. |
| Agent ei leia npm-i, vp-d või claude'i | Conductor käivitab skripte zsh-is ilma sinu täieliku kestaseadistuseta. Dokumentatsioon soovitab lisada seadistusskripti export PATH="$HOME/.local/bin:/opt/homebrew/bin:$PATH". |
npm error EBADDEVENGINES | Vite+ määratud npm 12 versioon. Viiba 1 esimene teadaolev probleem. |
Giti vead, näiteks fatal: bad object | Repo asub tõenäoliselt iCloudiga sünkroonitud kaustas. Klooni see uuesti kausta ~/Developer ja kustuta vana koopia. |
| GitHub Desktop ei vaheta haru | See haru on Conductor tööruumis avatud. Haru saab korraga asuda ühes kaustas. |
vp check ebaõnnestub veaga only-export-components | shadcni failid ekspordivad variante komponentide kõrval. 1. viibu teadaolev probleem 4. |
Töö Tests: Executable doesn't exist | Chromiumi ei paigaldatud käitajasse. Käivita töö käigus vp exec playwright install --with-deps chromium enne käsku vp test. |
CI ebaõnnestub veaga No test files found | 4. viip ühendati enne 3. viipa. Ühenda testikomplekt ja käivita kontrollid uuesti. |
| Suitsutest näeb sisselogimislehte või viga 401 | Möödamineku saladus puudub või genereeriti uuesti. Uuenda GitHubi saladust ja juuruta uuesti, sest vanad juurutused säilitavad vana saladuse. |
| Suitsutest ei käivitu kunagi | Vercel käivitab ainult need töövood, mis on harus main juba olemas. Ühenda esmalt töövoog. |
| Port on juba kasutusel | Käivitusskript peab edastama --port $CONDUCTOR_PORT. |
| Agendid rikuvad üksteise andmeid | Seadistusskript ei loo igale tööruumile eraldi Convexi juurutust. Paranda see ja loo uus tööruum. |
| Claude kasutab sinu paketi asemel API-krediiti | Sinu Macis on määratud ANTHROPIC_API_KEY. Conductori dokumentatsioon hoiatab, et see on tellimusest kõrgema prioriteediga. Eemalda see. |
Preview-keskkonna koostamine ebaõnnestub veaga No CONVEX_DEPLOYMENT set | Verceli Preview-keskkonnas puudub CONVEX_DEPLOY_KEY. Lisa eelvaatevõti, märkides ainult Preview, ja juuruta uuesti. |
| PR muutis tarbekeskkonna andmeid | Tarbekeskkonna võtmel on märgitud ka Preview. Eemalda sellelt Preview märge, lisa Preview jaoks eelvaatevõti ja juuruta eelvaade uuesti. |
| Tarbekeskkonna koostamine loob eelvaate taustsüsteemi | Eelvaatevõtmel on märgitud Production. Hoia iga keskkonna jaoks eraldi võti. |
| Verceli juurutus ebaõnnestub sammus Ignored Build Step | Giti viga pääses vahelejätmisskriptist välja. Iga tee peab lõppema käsuga exit 0 või exit 1; palu agendil skript parandada. |
| CI töö Build ütleb, et Convex codegen on aegunud | Convexi funktsioon muutus tüüpe uuesti genereerimata. Käivita npx convex codegen ja tee commit või lase seda teha ci-watch’il. |
Käsu /pre-review sisestamine ei tee midagi | 6. viip pole selle tööruumi harusse ühendatud. Ühenda see ja tõmba seejärel klahvidega ⌘⇧L haru main muudatused. |
| Plugina paigaldamisel ei leita turuplatsi | Käivita claude plugin marketplace add anthropics/claude-plugins-official ja paigalda frontend-design uuesti. |
Sinu agendi seaded