Claude Code pro týmy: Příručka pro standardizaci dovedností

Posaďte pět vývojářů k Claude Code a získáte pět různých nástrojů. Jeden má soubor CLAUDE.md se silnými názory na testování. Jiný nikdy neotevřel adresář skills. Další si před třemi týdny nainstaloval dovednost pro ladění z vlákna na GitHubu a zapomněl to někomu říct. Dva používají výchozí nastavení, což znamená, že Claude v každé relaci nově odhaduje jejich konvence.

Kód, který se dostane do vaší fronty PR, odráží tento rozdíl. Některé diffy přicházejí s nejprve napsanými testy a čistou historií commitů. Jiné přicházejí s věrohodně vypadající opravou chyby, kterou nikdo ve skutečnosti nediagnostikoval. Stejný model, stejný repozitář, stejný týden, pět různých kvalit výstupu, a recenzent to všechno zachytí ručně.

Toto je problém osobní konfigurace v hávu týmového problému. Individuálně je nastavení každého vývojáře obhajitelné. Kolektivně tým nemá žádné dno. Nikdo se neshodl na tom, jak vypadá „dobré“, když Claude dělá první návrh, takže nikdo to nemůže udržet. Tento článek je o řešení: dovednosti na úrovni projektu, které žijí v repozitáři namísto na noteboocích, a správa a zavádění, které zajistí jejich udržení.

Řešení je v tom, kde dovednost žije, ne v tom, co dělá

Claude Code čte dovednosti ze dvou míst. Osobní dovednosti se nacházejí v ~/.claude/skills/, jsou vázány na jeden stroj, neviditelné pro spoluhráče, pryč v okamžiku, kdy vývojář vymění notebook. Projektové dovednosti se nacházejí v .claude/skills/ uvnitř samotného repozitáře, commitované spolu s kódem, který řídí.

Toto druhé umístění je celý trik. Projektová dovednost je soubor v gitu: dostane diff, recenzenta, commit zprávu vysvětlující, proč by ladění mělo následovat cyklus nejprve hypotézy namísto toho, co se ten den zdálo správné. Když někdo dovednost vylepší, vylepšení se dostane ke všem při dalším pullu, stejně jako aktualizace konfigurace linteru.

Porovnejte to s alternativou, po které většina týmů sáhne jako první: wiki stránka s názvem „Jak používáme Claude“, kterou si přečetli tři lidé a nikdo ji nevymáhá. Wiki stránka je rada. Projektová dovednost je blíže závislosti: Claude načte její popis na začátku každé relace v daném repozitáři a automaticky ji aplikuje, když se úloha shoduje, aniž by si kdokoli musel pamatovat, že existuje, nebo ji znovu vysvětlovat v promptu.

Praktickým výsledkem je, že „standard našeho týmu“ přestává být větou v onboardingovém dokumentu a stává se něčím, co Claude skutečně dělá, identicky, ať už jde o relaci technického vedoucího nebo relaci nového zaměstnance v první den.

Co standardizovat jako první

Nesnažte se zakódovat celou svou inženýrskou kulturu do dovedností najednou. Tři oblasti pokrývají většinu rozdílů, které vidíme mezi vývojáři ve stejném týmu, a každá má otestovanou, ohodnocenou dovednost, na kterou můžete ukázat jako na konkrétní příklad toho, jak vypadá „dobré“, i když nakonec napíšete vlastní verzi vyladěnou pro váš stack.

Kontrolní seznam pro revize. Mezera mezi revizí, která najde skutečné chyby, a revizí, která najde preference pojmenování proměnných, je přesně to, co dobrá dovednost pro revize uzavírá. Code Review Checklist dosahuje v našem testování skóre 8.4/10: na 600řádkovém PR našla jednu skutečnou chybu off-by-one a dvě cesty s mrtvým kódem a nevyprodukovala žádné stylistické připomínky. Pokud každý recenzent získá takovou kvalitu prvního průchodu, než člověk otevře diff, seniorní inženýři tráví čas revizí architekturou namísto chytání toho, co by měl zachytit kontrolní seznam.

TDD disciplína. Test-Driven Development, z kolekce Superpowers Jesseho Vincenta, dosahuje skóre 9.6/10. Spustili jsme ji během relace se třemi funkcemi a Claude pokaždé nejprve napsal selhávající test, odmítl přeskočit cyklus, i když byla k dispozici zkratka. Je to čistě behaviorální dovednost, bez skriptů nebo externích nástrojů, což z ní dělá nejsnadnější věc k univerzalizaci: "write the test first" nezávisí na vašem frameworku.

Protokol pro ladění. Systematic Debugging, rovněž 9.6/10, nahrazuje výchozí smyčku „zkusit věrohodnou opravu“ cyklem reprodukce, hypotézy, instrumentace, ověření. V našem testu odhalil příčinu race condition, která již přežila tři opravy založené na odhadech. Toto je dovednost, která je v týmu nejdůležitější, protože ladění metodou pokus-omyl je zdrojem největší variability výstupu a sdílený protokol tuto mezeru zmenšuje.

Tři dovednosti. Ne dvacet, které budete v pokušení přidat, jakmile ty první tři začnou fungovat.

Kdo schvaluje novou dovednost

Jakmile dovednosti žijí v repozitáři, někdo musí rozhodnout, co se do něj přidá, a to je část, kterou týmy přeskakují, dokud se jim to nevymstí. Dovednost jsou instrukce, které Claude automaticky následuje, a někdy skripty, které Claude spustí, což ji řadí do stejné kategorie důvěry jako nový balíček npm nebo CI akci. Nikdo by nedovolil vývojáři přidat libovolnou závislost do package.json bez PR revize. Dovednost si zaslouží stejnou bránu.

Mechanika je jednoduchá, jakmile se zavážete k takovému přístupu. Nová dovednost vstupuje do repozitáře prostřednictvím běžného pull requestu, se stejnou ochranou větve jako jakákoli jiná změna. Recenzent přečte celý SKILL.md, kontroluje instrukce nesouvisející s uvedeným účelem a jakékoli síťové volání, jehož důvod není zřejmý. Pokud dovednost obsahuje skripty, někdo je skutečně otevře. Toto je stejný dvouminutový audit, kterým procházíme v našem bezpečnostním průvodci.

Přidělte vlastníka, jednu osobu spíše než komisi, obvykle toho, kdo dovednost navrhl, nebo rotujícího technického vedoucího, odpovědného za to, aby popis dovednosti zůstal přesný a její instrukce aktuální. Když se spouštěcí fráze dovednosti začne spouštět na nesprávné úlohy, nebo se její instrukce odchýlí od pracovního postupu, pro který byla napsána, tento vlastník ji opraví nebo stáhne.

Verzujte ji jako všechno ostatní v repozitáři. Pokud dovednost významně změní chování, stojí to za poznámku v popisu PR a, pro cokoli se skutečnou behaviorální váhou, zmínku na standupu, aby lidé věděli, že jejich relace se od dnešního dne budou chovat jinak.

Onboarding je skutečná killer funkce

Zde je část, kterou je snadné podcenit, když to prezentujete skeptickému vedoucímu týmu: nový zaměstnanec naklonuje repozitář první den a získá stejnou disciplínu revizí, stejný zvyk psát testy jako první a stejný protokol ladění jako osoba, která je tam dva roky. Ne proto, že by si pečlivě přečetli 40stránkový onboardingový dokument. Ale proto, že dovednosti již leží v .claude/skills/ a Claude je načte v okamžiku, kdy nový zaměstnanec otevře projekt.

Přemýšlejte o tom, jak obvykle vypadá onboarding bez tohoto. Seniorní inženýr vysvětlí filozofii testování týmu v rozhovoru 1:1, nový zaměstnanec přikývne a o tři týdny později se polovina z toho vypaří pod tlakem termínů, protože návyky vytvořené pod tlakem se automaticky přizpůsobí tomu, co je nejrychlejší. S projektovými dovednostmi není disciplína pamětí, kterou musí nový zaměstnanec udržovat. Je to infrastruktura, vynucovaná na jejich prvním PR stejně jako na stém.

Také to zmenšuje rozdíly napříč úrovněmi seniority. Relace juniorního vývojáře, která používá stejnou dovednost pro ladění jako relace zkušeného inženýra, produkuje výstup na mnohem bližší úrovni kvality, než by oba dosáhli bez pomoci, protože velká část toho, co odděluje dobrou ladicí relaci od špatné, je procedura, nikoli zkušenost.

Pokud jste ještě nenastavili zbytek vrstvy Claude Code, stojí za to to udělat před nebo souběžně s tímto. Náš průvodce nastavením pokrývá vrstvy CLAUDE.md a oprávnění, na kterých projektové dovednosti spočívají.

Jak poznat, zda to skutečně funguje

Odolejte nutkání vymýšlet pro to dashboard. Signál, který chcete, již proudí nástroji, které máte.

Sledujte objem komentářů k revizím PR a, co je důležitější, typ komentářů. Pokud recenzenti začnou zanechávat méně komentářů typu „testoval jsi to“ a „toto nezpracovává případ null“ a více komentářů o skutečných kompromisech v designu, dovednosti pro revize a TDD dělají svou práci. Pokud počet komentářů klesne, ale zbývající komentáře stále zachycují chyby správnosti, které by dovednost měla zachytit, dovednost ještě není správně vyladěna, nikoli tým.

Sledujte míru regresí. Dovednost ladění, která vynucuje disciplínu hypotéza-ověření, by měla znamenat méně „opravených“ chyb, které se znovu objeví o týden později, protože opravy metodou pokus-omyl jsou přesně ty, které se vracejí. Toto je pomalejší signál, obvykle viditelný během jednoho nebo dvou měsíců spíše než sprintu, ale je nejdůležitější pro tým, který se již dříve spálil na „opravených“ chybách.

Sledujte dobu do prvního schválení PR, přičemž jeden datový bod berte jako náznak a trvalý posun napříč několika sprinty jako skutečný signál. A mluvte s lidmi: zda vývojáři cítí, že výstup Claude se stal konzistentnějším, zda nový zaměstnanec říká, že kódová základna se mu zdála čitelnější rychleji než v jeho předchozí práci, má v prvním měsíci větší hodnotu než cokoli z výše uvedeného.

Čtyřtýdenní zavádění pro tým deseti lidí

Týden 1. Vyberte jeden repozitář, ne všechny, a jednu dovednost; kontrolní seznam pro revize je obvykle nejsnadnější prodat, protože recenzenti vidí přínos okamžitě. Přidejte jej do .claude/skills/ prostřednictvím běžného PR. Získejte dva nebo tři dobrovolníky, aby jej použili na svých několika dalších revizích a podali zprávu v krátkém vlákně, ne na schůzce.

Týden 2. Přidejte dovednost TDD do stejného repozitáře. Toto je ta, která se setkává s největším odporem, protože mění způsob, jakým lidé píší kód, spíše než jak ho revidují. Očekávejte tření a zacházejte s ním jako s daty. Dovednost ladění zatím vynechte a sbírejte konkrétní stížnosti ("spouští se na úkoly, kde to nechci") abyste opravili popis dovednosti, než se pokusíte opravit chování lidí.

Týden 3. Přidejte dovednost ladění. Tým už teď má představu o tom, jak se projektové dovednosti chovají, takže toto přidání by mělo jít rychleji. Udělejte krátké retro k datům za dva týdny: mění se komentáře k revizím, vyhýbá se někdo potichu dovednostem, proč. Upravte popisy spouštěčů, pokud se dovednost spouští příliš často nebo nedostatečně.

Týden 4. Rozšiřte stejné tři dovednosti na zbytek repozitářů týmu. Napište krátkou poznámku do README každého repozitáře, která říká, co je v .claude/skills/ a proč, aby se další nový zaměstnanec nemusel ptát. Nastavte proces schvalování z výše uvedené sekce jako trvalé pravidlo, protože skutečným testem správy je to, co se stane se čtvrtou dovedností, kterou někdo navrhne, ne s prvními třemi.

Čtyři týdny, tři dovednosti, jeden repozitář rozšířený na zbytek organizace. Odolejte zkracování; tření ve 2. týdnu je informace, kterou chcete mít, než budete spouštět pět dovedností napříč deseti repozitáři.

Možnost pluginu pro organizace s více repozitáři

Projektové dovednosti řeší standardizaci v rámci repozitáře, ale většina inženýrských organizací není jeden repozitář. Pokud vašich deset vývojářů pracuje na patnácti službách, kopírování .claude/skills/ do každého z nich a jejich ruční synchronizace se stane samostatnou údržbovou prací, která po druhém čtvrtletí tiše přestane probíhat.

Pluginy Claude Code řeší tuto vrstvu. Plugin balí sadu dovedností, plus příkazy a další konfiguraci, do jedné instalovatelné jednotky, která není vázána na historii gitu jednoho repozitáře. Namísto patnácti kopií stejných tří dovedností, které se nezávisle rozcházejí, organizace udržuje jeden plugin, jednou verzovaný, a každý repozitář z něj instaluje. Aktualizace dovednosti ladění se pak šíří všude, kde je plugin nainstalován, namísto vyžadování patnácti samostatných PR.

Toto je krok vpřed v operační složitosti a nestojí za to ho podnikat, dokud jste nepocítili bolest z udržování více repozitářů v synchronizaci. Pro tým deseti lidí na jednom nebo dvou repozitářích je přístup projektových dovedností v tomto článku správným koncovým bodem. Pro organizaci, která používá stejné standardy napříč mnoha kódovými základnami, náš průvodce pluginy pokrývá mechaniku balení a distribuce.

Režim selhání: nařízení dvaceti dovedností hned první den

Nejčastější způsob, jak se to pokazí, není technický, je to chyba při zavádění. Technický vedoucí si přečte o projektových dovednostech, nadchne se a během jednoho odpoledne commitne dvacet z nich: revize, TDD, ladění, plus tucet dalších pro konvence logování, formát commit zpráv, návrh API, přístupnost a cokoli dalšího, co se zdálo rozumné ve 4 odpoledne ve čtvrtek.

Dvě věci se pokazí. Zaprvé, překrývající se popisy se začnou spouštět na nesprávné úkoly, nebo na sebe navzájem, protože nikdo nezkontroloval, zda se spouštěcí fráze dovednosti tři nekoliduje s dovedností jedenáct; tyto konflikty jsou jedním z nejčastějších defektů, které vidíme při testování, a zhoršují se s rostoucím počtem. Zadruhé, a to je škodlivější, tým nikdy nevybuduje důvěru v dovednosti, protože týden pod dvaceti novými pravidly působí jako cvičení v dodržování předpisů a lidé začnou pracovat kolem Claude namísto s ním.

Tři dovednosti, přijaté během měsíce, se skutečnou zpětnou vazbou formující každou z nich před příchodem další, budují důvěru, kterou dvacet dovedností najednou nikdy nevybuduje. Pokud se váš tým stále rozhoduje, kde začít, naše žebříčky kódovacích dovedností jsou seřazeny podle testovaného skóre, což je rozumný filtr pro výběr další po vašich prvních třech.

Často kladené otázky

Fungují dovednosti na úrovni projektu stejně jako ty osobní?

Ano, formát je identický. Jediný rozdíl je v umístění: .claude/skills/ v repozitáři namísto ~/.claude/skills/ na notebooku. Claude Code načítá obojí stejným způsobem. Pokud dovednost existuje na obou místech se stejným názvem, projektová verze má obecně přednost pro daný repozitář, což je přesně chování, které chcete pro týmový standard.

Zpomalí to Claude pro všechny v týmu?

Sotva. Každá nainstalovaná dovednost stojí zhruba 100 tokenů vždy načtených metadat. Tři projektové dovednosti napříč týmem přidávají méně stálého kontextu, než obvykle dělá jeden připojený server MCP. Skutečné náklady na to, když se to pokazí, není rychlost, ale zmatek ve spouštění z překrývajících se popisů, a proto plán zavádění výše přidává dovednosti jednu po druhé.

Co když vývojář nesouhlasí s týmovým standardem TDD nebo ladění?

To je konverzace, kterou je třeba vést před sloučením dovednosti, v revizi PR, na stejném místě, kde byste ji vedli o pravidle linteru. Jakmile je v repozitáři, platí pro všechny, ale „všichni“ by měli znamenat, že každý měl možnost se vyjádřit během revize, ne že jedna osoba rozhodla jednostranně a pushla do main.

Měli bychom dovednosti vyžadovat, nebo je nechat volitelné?

Projektové dovednosti se automaticky načítají pro každého, kdo má repozitář, takže neexistuje žádný samostatný krok „vyžadovat“, jsou prostě součástí kódové základny. Co můžete učinit volitelným, je příspěvek: ne každý vývojář musí navrhovat nové dovednosti, ale relace každého vývojáře spouští ty, které jsou sloučeny. Rozhodnutí o sloučení berte jako bránu.

Jak se to liší od pouhého napsání dlouhého CLAUDE.md?

Chování při načítání. CLAUDE.md se načítá do každé relace bez ohledu na to, co vývojář ten den dělá, což je správné pro fakta, která platí vždy: build commands, architektura, konvence pojmenování. Dovednost se načítá pouze tehdy, když se úloha shoduje s jejím popisem, což je správné pro proceduru, kterou někdy potřebujete: jak tým ladí, jak tým reviduje. Pokud váš CLAUDE.md obsahuje dlouhou sekci popisující, jak psát testy nebo strukturovat revizi, tato sekce se chce stát spíše dovedností.