Demo komponentów Starlight

Wzornik komponentów Starlight zbiera na jednej stronie każdy komponent MDX i konwencję formatowania używaną w artykułach AI Developer Toolkit — asides, karty, taby, kroki, drzewa plików, badge i karty linków — jako żywe odniesienie pokazujące, jak każdy komponent się renderuje i kiedy po niego sięgać.

Warianty Aside

Asides podkreślają ważne informacje. Każdy wariant sygnalizuje inny zamiar.

Notatka

Używaj note dla dodatkowego kontekstu, który czytelnik powinien być świadomy, ale może pominąć bez utraty głównego wątku. Przykład: “Dostępność i ceny modeli zmieniają się często. Weryfikuj aktualne ceny przed podejmowaniem decyzji.”

Wskazówka

Używaj tip dla promptów do kopiowania-wklejania i porad praktycznych. Przykładowy prompt:

Przejrzyj ten plik pod kątem luk bezpieczeństwa. Skup się na SQL injection, XSS i obejściu uwierzytelniania. Ignoruj kwestie stylu.

Każdy artykuł o przepływie pracy zawiera co najmniej 2-3 aside’y tip z gotowymi do użycia promptami.

Uwaga

Używaj caution dla typowych pułapek i “gotchas”, które wpadają programistom. Przykład: “Uruchamiaj --dangerously-skip-permissions wyłącznie w jednorazowym sandboksie z ograniczoną siecią, na przykład w wyrzucanym po użyciu kontenerze albo maszynie wirtualnej bez sekretów. Ta flaga omija wszystkie kontrole uprawnień, a runner CI, który ma sekrety, nie jest takim sandboksem.”

Ważne

Używaj danger dla nieodwracalnych działań lub ostrzeżeń krytycznych dla bezpieczeństwa. Przykład: “Nigdy nie commituj kluczy API lub sekretów do kontroli wersji. Używaj zmiennych środowiskowych i plików .env wykluczonych przez .gitignore.”

Tabs dla porównań trzech narzędzi

Główny wzorzec w całym AI Developer Toolkit. Każdy wspólny przepływ pracy używa trzech zakładek.

Cursor

Cursor to narzędzie IDE-first. Przepływy pracy dzieją się wewnątrz edytora z wizualną informacją zwrotną.

Cmd/Ctrl+I    Otwórz czat Agent
Cmd/Ctrl+K    Edycja wbudowana
Tab           Zaakceptuj autouzupełnienie
@file.ts      Referencja pliku

Kluczowe funkcje: Autouzupełnianie Tab, Background Agent, BugBot, punkty kontrolne, wizualne diffy.

Claude Code

Claude Code to narzędzie CLI-first. Przepływy pracy dzieją się w terminalu z interakcją tekstową.

claude                    # Uruchom sesję interaktywną
claude -p "napraw błąd"   # Jednorazowe zapytanie
/compact                  # Podsumuj rozmowę
@file.ts                  # Referencja pliku

Kluczowe funkcje: Hooki, niestandardowe slash commands, tryb headless, piping, zarządzanie sesjami.

Codex

Codex to narzędzie multi-powierzchniowe. Przepływy pracy obejmują App, CLI, rozszerzenie IDE i agentów Cloud.

codex                              # Uruchom sesję interaktywną
codex "zaimplementuj funkcję"      # Rozpocznij z promptem
codex -a never --sandbox workspace-write  # Zaufane zadanie unattended; jawny sandbox

Kluczowe funkcje: Git worktrees, automatyzacje GitHub/Slack/Linear, agenci w chmurze, tryby zatwierdzania.

Zagnieżdżone Tabs

Tabs mogą być zagnieżdżone dla sub-porównań wewnątrz sekcji narzędzia:

Według zadania

Zadanie	Rekomendowany model
Złożone refaktoryzacje wielu plików, budowanie od zera	Claude Fable 5
Złożona architektura	Claude Opus 5
Codzienne kodowanie	Claude Sonnet 5
Iteracja wymagająca szybkości	Cursor Composer 2.5
Naprawa błędów w Cursor	GPT-5.6 Sol
Wszystkie przepływy pracy Codex	GPT-5.6 Sol

Według budżetu

Budżet	Model podstawowy
Najwyższa jakość	Claude Fable 5
Premium	Claude Opus 5
Standardowy	Claude Sonnet 5
Wrażliwy na koszty	GPT-5.6 Sol

Bloki kodu

Podświetlanie składni z tytułem

src/lib/auth.ts

interface AuthResult {
  success: boolean;
  user?: User;
  error?: string;
}

export async function authenticateUser(
  token: string
): Promise<AuthResult> {
  try {
    const payload = await verifyJWT(token);
    const user = await db.users.findById(payload.sub);
    return { success: true, user };
  } catch (error) {
    return { success: false, error: "Nieprawidłowy token" };
  }
}

Podświetlanie linii i znaczniki diff

config.js

// Aktualizacja konfiguracji
const config = {
  port: process.env.PORT || 3000,
  database: process.env.DATABASE_URL,
  cacheEnabled: true,       // Dodano: włącz cachowanie
  // debugMode: true,       // Usunięto: wyłącz debug w produkcji
};

Polecenia Shell

# Zainstaluj zależności
npm install @anthropic-ai/claude-code
claude --version

# Zainicjalizuj konfigurację projektu
claude
/init

Przykłady wielu języków

TypeScript

const users = await db
  .select()
  .from(usersTable)
  .where(eq(usersTable.role, "admin"));

Python

users = await db.execute(
    select(users_table).where(
        users_table.c.role == "admin"
    )
)

Go

var users []User
err := db.Where("role = ?", "admin").Find(&users).Error

Karty i siatki kart

Pojedyncze karty

Kluczowa koncepcja

Karty dobrze sprawdzają się dla samodzielnych wyjaśnień, definicji lub wywołań, które zasługują na wizualną separację od głównego przepływu tekstu.

Siatki kart

Cursor

Rozwój IDE-first z wizualną edycją, trybem agenta, autouzupełnianiem tab i agentami w tle.

Claude Code

Rozwój CLI-first z przepływami pracy w terminalu, hookami, niestandardowymi poleceniami i integracją CI headless.

Codex

Rozwój multi-powierzchniowy obejmujący App, CLI, IDE i Cloud z automatyzacjami i worktrees.

Karty linków

Skróty klawiszowe Kompletne tabele skrótów dla wszystkich trzech narzędzi

Ściągawka poleceń Każde polecenie CLI, slash command i symbol kontekstowy

Komponent Steps

Steps renderuje numerowany przewodnik proceduralny. Komponent oczekuje pojedynczej listy uporządkowanej.

1. Zainstaluj narzędzie

   Wybierz swoje preferowane narzędzie do kodowania AI i zainstaluj je zgodnie z przewodnikiem szybkiego startu.

2. Skonfiguruj kontekst projektu

   Utwórz plik konfiguracyjny (.cursor/rules/, CLAUDE.md lub AGENTS.md) ze stosem technologicznym projektu, standardami kodowania i typowymi poleceniami.

3. Skonfiguruj serwery MCP

   Zainstaluj serwery MCP dla swoich zewnętrznych narzędzi (baza danych, przeglądarka, hosting Git), aby dać AI bezpośredni dostęp.

4. Zacznij od prawdziwego zadania

   Wybierz zadanie o niskim ryzyku ze swojego backlogu — poprawkę błędu, test lub małą funkcję. Przepracuj je z AI i iteruj swoje prompty.

5. Przejrzyj i udoskonalaj

   Po pierwszej sesji zaktualizuj swój plik konfiguracyjny na podstawie tego, co zadziałało i czego AI się pomyliło. Konfiguracja poprawia się z każdą sesją.

Drzewo plików

• Foldersrc/

  • Foldercomponents/

    • Header.astro
    • Footer.astro
    • PaywallModal.tsx
  • Foldercontent/

    • Folderdocs/

      • Folderen/

        • Folderstart/

          • …
        • Foldercursor-ide/

          • …
        • Folderclaude-code/

          • …
        • Foldercodex/

          • …
        • Folderworkflows/

          • …
        • Folderreference/

          • …
        • Folderresources/

          • …
      • Folderpl/

        • …
  • Folderlib/

    • Folderdb/

      • schema.ts
      • queries.ts
    • auth.ts
  • Folderpages/

    • Folderapi/

      • Foldersubscription/

        • …
      • Folderauth/

        • …
    • index.astro
• CLAUDE.md
• Folder.cursor/

  • Folderrules/

    • project.mdc
• AGENTS.md
• package.json
• astro.config.mjs

Tabele

Prosta tabela

Funkcja	Cursor	Claude Code	Codex
Autouzupełnianie Tab	Tak	Nie	Nie
Agenci w tle	Tak (local/cloud/Automations)	Tak (background, web/desktop, Routines)	Tak (opcjonalne worktree desktopowe / Cloud)
Serwery MCP	Tak	Tak	Tak
Integracja Git	Wbudowana	Przez narzędzia	Wbudowana; izolacja zależy od powierzchni
Niestandardowe polecenia	Commands/skills/plugins	.claude/commands/ + skills/plugins	Slash commands/skills

Szczegółowa tabela porównawcza

Model	Dostawca	Kontekst	Wejście $/1M	Wyjście $/1M	Typowe użycie
Claude Fable 5	Anthropic	1M	$10	$50	Najtrudniejsze refaktoryzacje, budowanie od zera
Claude Opus 5	Anthropic	1M	$5	$25	Złożona architektura
Claude Sonnet 5	Anthropic	1M	$2*	$10*	Codzienne kodowanie
GPT-5.6 Sol	OpenAI	1,05M	$5	$30	Najtrudniejsze przepływy pracy Codex
Gemini 3.1 Pro	Google	1M	$2	$12	Analiza multimodalna

* Promocyjna cena Sonnet 5 do 31 sierpnia 2026; potem $3/$15.

Odznaki

Odznaki dodają wskaźniki statusu inline:

• Nowe — Nowe funkcje lub niedawno dodana treść
• Zaktualizowane — Niedawno zaktualizowane sekcje
• Przestarzałe — Funkcje wycofywane
• Przełomowe — Przełomowe zmiany wymagające działania
• Stabilne — Funkcje gotowe do produkcji

Zwijane Details

Zaawansowane: Łączenie serwerów MCP z niestandardowymi poleceniami

Możesz tworzyć niestandardowe slash commands w Claude Code, które wykorzystują serwery MCP dla wieloetapowych przepływów pracy:

---
allowed-tools: [Read, Edit, Bash, mcp__github__create_pull_request]
description: Utwórz PR z bieżących zmian
---

1. Uruchom: !git diff --stat
2. Podsumuj zmiany
3. Utwórz PR z opisowym tytułem i treścią
4. Zgłoś URL PR

Ten wzorzec działa, ponieważ narzędzia MCP są dostępne jako allowed-tools w definicjach niestandardowych poleceń.

Zaawansowane: Reguły Cursor z aktywacją wybraną przez agenta

Gdy pomijasz zarówno alwaysApply jak i globs, reguła staje się “wybrana przez agenta”. Cursor czyta pole description i decyduje czy reguła jest istotna dla bieżącego zadania:

---
description: "Wzorce migracji bazy danych używające Drizzle ORM. Używaj przy tworzeniu lub modyfikowaniu schematów bazy danych."
---

## Reguły migracji
- Zawsze twórz nowy plik migracji, nigdy nie modyfikuj istniejących
- Uruchom `npm run db:migrate` po utworzeniu migracji
- Testuj migracje za pomocą `npm run db:migrate:dry`

To jest przydatne dla wyspecjalizowanych reguł, które stosują się tylko do pewnych typów zadań.

Formatowanie Markdown

Kod inline i skróty klawiszowe

Referencjonuj polecenia jak /compact, pliki jak CLAUDE.md i skróty klawiszowe jak Cmd+I używając formatowania kodu inline.

Blockquotes dla promptów

Gdy pokazujesz prompt, który użytkownik powinien wpisać lub wkleić:

Przejrzyj ten middleware uwierzytelniania pod kątem luk bezpieczeństwa. Sprawdź: problemy z walidacją JWT, brakujące ograniczenie częstotliwości, luki w ochronie CSRF i ryzyko fiksacji sesji. Zasugeruj poprawki z kodem.

Listy

Listy nieuporządkowane dla zestawów funkcji i opcji:

• Serwery MCP zapewniają trwałe połączenia narzędziowe
• Agent Skills oferują lekkie, możliwe do udostępnienia możliwości
• Niestandardowe polecenia tworzą przepływy pracy wielokrotnego użytku
• Hooki przechwytują i modyfikują zachowanie AI w określonych punktach

Listy uporządkowane dla procedur sekwencyjnych:

1. Przeczytaj uważnie komunikat błędu
2. Sprawdź odpowiedni plik logu
3. Przeszukaj bazę kodu dla niedziałającej funkcji
4. Poproś AI o wyjaśnienie trybu awarii
5. Zaimplementuj i przetestuj poprawkę

Odniesienie struktury artykułu

Każdy artykuł w AI Developer Toolkit (z wyjątkiem stron indeksowych) stosuje się do tej struktury:

Standardowa anatomia artykułu

1. Zaczepka problemowa (2-3 zdania) — Scenariusz, który czytelnik rozpoznaje z prawdziwej pracy
2. Co z tego wyniesiesz — Lista punktowana konkretnych wyników
3. Przepływ pracy — Krok po kroku z prawdziwymi promptami i interakcjami narzędziowymi
4. Prompty do kopiowania-wklejania — Gotowe do użycia prompty w blokach <Aside type="tip">
5. Gdy to się psuje — Typowe tryby awarii i strategie naprawy
6. Co dalej — Linki do powiązanych artykułów

Ta struktura zapewnia, że każdy artykuł dostarcza natychmiastową, praktyczną wartość zamiast abstrakcyjnej teorii.