Jak používáme Claude Code Skills k formalizaci našich vývojových vzorů

Každý kód má své vzory. Způsob, jakým píšete testy, strukturujete komponenty, propojujete API — tyto konvence žijí v kolektivní paměti týmu, roztroušené mezi code reviews, onboardingovými dokumenty a kmenovou znalostí. Když do mixu přidáte AI asistenta pro kódování, nic z toho nezná. Napíše naprosto validní kód, který poruší každou konvenci, kterou jste zavedli.

Claude Code Skills tento problém řeší tím, že vám umožní zakódovat vaše vzory jako znovupoužitelné šablony, které Claude automaticky načte, když je to relevantní.

Co jsou Skills?

Skill je Markdown soubor v .claude/skills/<název>/SKILL.md s YAML frontmatter, který Claudovi říká, kdy se má aktivovat a jaké vzory následovat. Představte si je jako kontextové style guides, které se načítají na vyžádání.

---
name: unit-test
description: "Generate unit tests for backend services. Use when writing
  tests for query handlers, data fetchers, services, or domain logic."
---

# Unit Test Generator
...šablony a pravidla...

Pole description funguje jako spouštěč — Claude ho čte, aby rozhodl, zda má skill pro aktuální úkol načíst. Buďte konkrétní ohledně toho, kdy se má aktivovat.

Skills, které jsme vytvořili (a proč)

Provozujeme Spring Boot + Vue.js monorepo s CQRS/event-sourced backendem a micro-frontend architekturou. Zde jsou kategorie skills, které jsme vytvořili, a problémy, které řeší.

1. Skills pro unit testy

Náš největší problém byly AI-generované testy používající @MockBean (který vytváří nový Spring kontext pro každou unikátní sadu mocků, čímž ničí výkon testů) nebo @SpringBootTest (který načítá celou aplikaci). Naše konvence je ruční mockování s constructor injection:

class OrderServiceSpec extends Specification {

    OrderRepository repository = Mock()

    @Subject
    OrderService service

    def setup() {
        service = new OrderService(repository)
    }

    def "should return order when found"() {
        given:
        def query = new FindOrderQuery("order-1")

        when:
        def result = service.findById(query).block()

        then:
        1 * repository.findById("order-1") >> Mono.just(mockOrder)

        and:
        result != null
        result.id() == "order-1"
    }
}

Skill kóduje tento vzor plus specifické záludnosti frameworku: výchozí hodnoty Stub() nelze přepsat v given: blocích, reaktivní metody vyžadují .block() a ověření interakcí patří do then: před aserce v and:.

2. Skills pro testy event handlerů / projekcí

Naše event-sourced architektura obaluje každý event handler retry/dead-letter-queue službou. Bez skillu Claude generuje testy, které mockují wrapper jako no-op — ale skutečný wrapper vykonává handler funkci. Skill učí správný mock pattern:

def setup() {
    // Mock wrapperu musí skutečně vykonat handler lambdu
    retryService.withRetry(_, _, _, _, _) >> { args ->
        def event = args[0]
        def handler = args[4]
        handler.apply(event).onErrorResume { Mono.empty() }
    }
    projection = new OrderProjection(repository, retryService)
}

Tento jediný vzor by vývojáři trvalo 20 minut odhalit z existujícího kódu. Se skillem je to okamžité.

3. Skills pro integrační testy

Integrační testy proti reálným databázím (přes Testcontainers) vyžadují v naší kódové bázi specifické nastavení: rozšířit sdílenou základní třídu, importovat testovací konfiguraci, deklarovat skenování repozitářů s přesným balíčkem modulu a použít resource locks pro prevenci konfliktů při paralelním spouštění. Vynechejte jakýkoli krok a dostanete kryptické chyby Spring kontextu.

Skill kóduje celý boilerplate:

@SpringJUnitConfig(OrderIntegrationTest.TestConfig.class)
@ResourceLock("DB_ORDER_TESTS")
class OrderIntegrationTest extends AbstractDatabaseIntegrationTest {

    @TestConfiguration
    @Import(DatabaseTestConfig.class)
    @EnableRepositories(basePackages = "com.example.order.infrastructure")
    static class TestConfig { }

    @Autowired
    private OrderRepository repository;

    // Testy běží proti reálné Testcontainer databázi
    // Cleanup je automatický díky zděděnému @AfterEach
}

4. Skills pro API vrstvu (GraphQL / REST)

Naše API vrstva má vlastní vzory pro autentizaci, validaci vstupů a mapování typů. Klíčová konvence v naší modulitní architektuře: mappery musí zůstat v rámci hranice svého modulu. Přidání typů specifických pro modul do sdíleného mapperu porušuje architektonické hranice a způsobí selhání testů modularity.

Skill kóduje:

• Jak zapojit autentizaci (který supplier použít, kterému se vyhnout)
• Kde probíhá validace vstupů (na úrovni schématu, ne anotací — framework ignoruje @Valid na určitých typech vstupů)
• Jak strukturovat tok request-command-query-response
• Který mapper patří kam

5. Skills pro frontendové komponenty

Toto je náš nejkomplexnější skill. Pokrývá tři archetypy stránek, které jsme standardizovali napříč našimi micro-frontendy:

Management stránky (CRUD tabulky): List layout wrapper + vyhledávací řádek + server-side data tabulka s responzivním skrýváním sloupců + prázdný stav.

Explore stránky (mřížky karet): Stejný list layout + breadcrumb navigace + přepínač zobrazení (mřížka/mapa) + responzivní mřížka karet.

Detail stránky: Detail layout wrapper + hero obrázek + záložková navigace + kontextový panel akcí.

Skill také kóduje naši typografickou škálu (statistická čísla používají konkrétní velikost nadpisu — ne větší, které vypadají na mobilu přehnaně), importovací konvence (typy z centralizovaného balíčku, nikdy lokální definice) a specifické záludnosti komponent (určité Vuetify komponenty se musí importovat přímo, ne přes náš sdílený wrapper, aby si zachovaly interaktivní chování).

6. Skills pro operace / debugování

Referenční příručka pro přístup k produkčním databázím přes náš Kubernetes bastion pod. Tento skill se aktivuje, když se někdo ptá na debugování produkčních problémů — poskytne přesné příkazy, běžné diagnostické dotazy a bezpečnostní pravidla (vždy nejdřív čtěte, pak pište; vždy po sobě ukliďte), aniž by kdokoli musel hledat dokumentaci.

Jak psát efektivní Skills

1. Vycházejte ze skutečných problémů

Nepište skills spekulativně. Počkejte, až Claude vygeneruje kód porušující konvenci, a pak zakódujte opravu. Naše nejlepší skills vzešly ze skutečných bugů:

• Test, který prošel lokálně, ale selhal v CI, protože mock nevykonával handler funkci
• Selhání architektonického testu, protože mapper byl umístěn ve špatném modulu
• Mobilní UI drawer, který se nezavíral, protože wrapper komponenty nezachoval interaktivní chování

2. Vysvětlete “proč”

Pravidlo bez kontextu se slepě dodržuje nebo se v nevhodnou chvíli ignoruje. Porovnejte:

<!-- Slabé -->
Nikdy nepoužívejte @MockBean v testech.

<!-- Silné -->
Nikdy nepoužívejte @MockBean — každá unikátní sada mock beanů vytvoří nový
Spring kontext, čímž zničí výkon startu testů. Místo toho použijte ruční
mocky v setup() s constructor injection.

Když Claude chápe, proč pravidlo existuje, dokáže lépe rozhodovat v hraničních případech.

3. Ukažte šablonu, pak pravidla

Strukturujte skills takto: nejdřív šablona kódu, pak pravidla a záludnosti. Claude lépe následuje konkrétní příklad než interpretuje abstraktní pokyny.

4. Buďte konkrétní v popisu

Pole description určuje, kdy Claude skill načte. Obecné popisy plýtvají kontextem na irelevantní úkoly:

# Příliš široké — načte se při každém backendovém úkolu
description: "Backend development helper"

# Přesné — načte se pouze při psaní testů event handlerů
description: "Generate tests for event handler projections. Use when writing
  tests for event handlers that project events into read models. Handles
  retry service mocking and reactive event processing."

5. Udržujte skills zaměřené

Jeden skill na jeden vzor. Nekombinujte “napiš API endpoint” s “napiš jeho test” — to jsou oddělené úkoly, které nastávají v různou dobu. Menší skills se načítají rychleji a neznečišťují kontext irelevantními šablonami.

Kumulativní efekt

Sedm skills nemusí znít jako moc, ale kumulativní efekt je značný. Každý skill zabraňuje celé kategorii chyb:

Po několika týdnech používání skills naše připomínky při code review k AI-generovanému kódu znatelně klesly. Vzory, které dříve vyžadovaly komentáře “vlastně to děláme takhle”, nyní přicházejí správně na první pokus.

Jak začít

1. Vytvořte .claude/skills/<název>/SKILL.md ve vašem repozitáři
2. Přidejte YAML frontmatter s name a description
3. Napište šablonu kódu a pravidla v Markdownu
4. Commitněte do repozitáře — skills jsou verzovány spolu s kódem

Skills se načítají na vyžádání podle kontextu úkolu, takže není žádný výkonnostní náklad za to, že jich máte hodně. Začněte vzorem, který způsobuje nejvíce opakovaných korekcí ve vašich code reviews.

Další čtení:

• Dokumentace Claude Code Skills
• Přehled Claude Code
• CLAUDE.md — Instrukce pro projekt
• Claude Code Hooks
• Claude Code na GitHubu

Titulní foto: 5010 na Unsplash.