Jak zbudowałem własnego asystenta AI z plików .md - Claude Code, frontmatter, Obsidian i hooki

Większość ludzi używa AI jak jednorazowego czatu. Otwierasz okno, wklejasz kontekst, zadajesz pytanie, zamykasz temat. Następnego dnia robisz to samo od nowa.

Problem w tym, że to skaluje się słabo niezależnie od roli. Czy jesteś programistą, księgowym, grafikiem, maszynistą, specjalistą SEO czy właścicielem małej firmy, mechanika często jest podobna: bez dobrze przygotowanego kontekstu AI startuje zbyt ogólnie.

Da się to obejść. Nie przez “mądrzejszy model”, tylko przez lepszy system dostarczania kontekstu.

W tym artykule pokazuję jak taki system zbudować krok po kroku - od prostego pliku tekstowego do bardziej uporządkowanego workflow z metadanymi, rolami i automatyzacją.

Zanim przejdziemy dalej, jedna ważna rzecz: ten tekst nie jest o samym claude.ai w przeglądarce. Mowa o Claude Code, czyli narzędziu CLI od Anthropic, które działa w terminalu, widzi katalog projektu i potrafi czytać pliki, uruchamiać komendy i edytować repozytorium.

Zanim zaczniesz: co musisz mieć

Jeśli znasz tylko czat w przeglądarce, to właśnie tutaj najłatwiej się odbić. Claude Code nie jest “kolejnym oknem czatu”. To narzędzie działające w katalogu projektu.

Na start potrzebujesz:

aktywnej subskrypcji Claude (Pro, Max, Team albo Enterprise) albo konta w Anthropic Console / wspieranym providerze,
terminala,
katalogu projektu, w którym chcesz pracować,
na Windowsie także Git for Windows,
zainstalowanego Claude Code.

Według oficjalnego quickstartu Anthropic, Claude Code instalujesz natywnie z terminala:

irm https://claude.ai/install.ps1 | iex

Po instalacji wchodzisz do katalogu projektu i odpalasz:

claude

Przy pierwszym uruchomieniu logujesz się do konta. Oficjalne docs startowe:

https://code.claude.com/docs/en/overview
https://code.claude.com/docs/en/quickstart

To brzmi banalnie, ale ma praktyczną konsekwencję: cały system opisany niżej żyje w plikach obok projektu, a nie w historii jednego czatu w przeglądarce.

Problem: AI bez kontekstu to biała kartka przy każdej sesji

W wielu codziennych workflowach rozmowa z Claude, ChatGPT czy Copilotem i tak zaczyna się praktycznie od zera. Narzędzie może mieć historię, pamięć albo kontekst workspace, ale dalej często nie zna Twoich bieżących priorytetów, decyzji z wczoraj i operacyjnego stanu pracy.

Typowy workflow większości ludzi pracujących z wiedzą:

Otwierasz chat
Wklejasz długi prompt z kontekstem (“jestem [twoja rola], pracuję nad [obszar], dziś priorytetem jest [X], wczoraj ustaliliśmy że…”)
Dostajesz odpowiedź
Następna sesja - zaczynasz od nowa

To jest strata czasu i źródło błędów. AI odpowiada na pytanie jakie zadałeś, nie na pytanie w kontekście Twojej rzeczywistości.

Rozwiązanie jest prostsze niż myślisz.

Krok 1 - CLAUDE.md: fundament systemu

Claude Code czyta plik CLAUDE.md automatycznie przy każdej sesji. To Twój punkt startowy.

I tu od razu doprecyzowanie, którego zwykle brakuje w podobnych wpisach: oficjalne lokalizacje to CLAUDE.md w rootcie projektu albo .claude/CLAUDE.md. W praktyce, jeśli chcesz prosty setup dla jednego repo, trzymaj CLAUDE.md w rootcie. Jeśli budujesz więcej konfiguracji wokół Claude Code, wygodniej mieć wszystko pod .claude/.

Zamiast wklejać kontekst przy każdej rozmowie - raz go opisujesz i nigdy nie wracasz do tego tematu.

Minimalna wersja, która działa niezależnie od branży:

# Kim jestem i nad czym pracuję

Jestem [rola].
Na co dzień odpowiadam za [zakres odpowiedzialności].
Aktualnie prowadzę [projekty / klientów / obszary].

## Styl pracy
- Odpowiedzi krótkie i konkretne
- Nie powtarzaj kontekstu który już znasz
- Jeśli widzisz ryzyko - mów wprost

## Aktualne priorytety
- Priorytet 1: [najważniejszy cel]
- Priorytet 2: [drugi cel]
- Deadline: [co musi być dowiezione w tym tygodniu]

To już zwykle daje wyraźnie lepsze odpowiedzi przy minimalnym koszcie setupu.

Ale to dopiero początek.

Jak wygląda katalog po prostym setupie

Jeżeli nigdy tego nie robiłeś, to właśnie takiego widoku brakuje najczęściej. Minimalna struktura może wyglądać tak:

twoj-projekt/
  CLAUDE.md
  .claude/
    settings.json
    agents/
      strateg.md
      operacje.md
      kreator.md
  context/
    goals.md
    tasks.md
    contacts.md
    protocols/
      decision-filter.md

Co tu jest konwencją oficjalną, a co moją warstwą porządku?

CLAUDE.md - oficjalne miejsce na instrukcje i trwały kontekst pisany ręcznie.
.claude/settings.json - oficjalne miejsce na ustawienia projektu, w tym hooki.
.claude/agents/*.md - oficjalne miejsce na własnych agentów projektowych.
context/ - już moja konwencja. To może nazywać się notes/, knowledge/, crm/ albo jakkolwiek chcesz.

To ważne, bo bez tego łatwo pomylić dwie rzeczy: co jest funkcją Claude Code, a co jest po prostu sensownym układem plików wokół niego.

To może wyglądać różnie zależnie od zawodu:

Janek z developmentu wpisze sprint, bugi i decyzje architektoniczne.
Jurek z księgowości wpisze zamknięcie miesiąca, dokumenty do wyjaśnienia i terminy podatkowe.
Grafik wpisze aktywne projekty, feedback od klientów i status assetów.
Specjalista SEO wpisze klastry contentowe, strony do optymalizacji i KPI na kwartał.
Maszynista wpisze procedury, harmonogram, wyjątki i checklisty operacyjne.

Krok 2 - frontmatter: metadane które AI skanuje bez czytania treści

Gdy masz 10, 20, 50 plików z kontekstem - AI nie może czytać wszystkich przy każdej sesji. Tu wchodzi frontmatter.

Każdy plik .md zaczyna się od bloku YAML:

---
type: crm-contact
contact: "Kontakt A"
company: "Firma A"
stage: DISCOVERY
last_contact: 2026-04-02
next_action: "Discovery call - 7 kwietnia 14:00, wideorozmowa"
deadline: 2026-04-07
---

Efekt: zamiast czytać cały plik historii kontaktu, AI skanuje 8 linii frontmattera i wie: kto to jest, na jakim etapie jest sprawa, co trzeba zrobić i kiedy.

Tu jednak trzeba rozdzielić marketingową metaforę od mechaniki.

Claude Code nie robi magicznego indeksowania całego vaulta po YAML-u tylko dlatego, że dodałeś frontmatter. To nie działa tak, że wrzucasz 200 plików do katalogu, a model automatycznie zna wszystkie ich pola.

W praktyce są trzy poziomy użycia frontmattera:

najprostszy: Claude otwiera konkretny plik i od razu dostaje uporządkowany kontekst na górze,
średni: Ty albo skrypt wybieracie pliki po nazwach, folderach i metadanych, a Claude czyta już wyselekcjonowany zestaw,
bardziej dojrzały: frontmatter staje się paliwem dla własnego indeksu, hooka, Obsidian CLI albo lokalnego RAG.

Innymi słowy: frontmatter sam w sobie nie rozwiązuje discovery. On rozwiązuje strukturę. Discovery musisz dobudować workflowem.

Ten sam pattern działa szerzej niż tylko CRM:

---
type: protocol
trigger: "Użytkownik pyta 'czy to ma sens' / 'czy warto' / rozważa nowy kierunek"
auto_trigger: false
read_by: [strateg, reviewer]
---

---
type: strategy
purpose: "Proces pracy - etapy, obiekcje, checklisty, decyzje"
read_by: [crm, call-brief]
review_frequency: weekly
---

Albo tak:

---
type: task-brief
owner: "SEO"
project: "Klaster artykułów Q2"
status: IN_PROGRESS
next_action: "Zaktualizować brief dla 3 tekstów"
deadline: 2026-04-09
---

Frontmatter nie jest tylko dla sprzedawców. To po prostu szybki indeks kontekstu.

Zamiast szukać co gdzie jest - AI czyta metadane i wie co warto przeczytać w danym kontekście.

Lepiej powiedzieć to precyzyjnie: gdy już wskażesz właściwy plik lub zestaw plików, frontmatter skraca drogę od “otwieram notatkę” do “rozumiem jej rolę”.

Krok 3 - backlinki i Obsidian: porządek relacji między plikami

Sama lista plików to za mało. Prawdziwa wartość pojawia się gdy AI rozumie relacje między nimi.

Tu wchodzi Obsidian i backlinki w formacie [[nazwa-pliku|etykieta]].

Przykład z pliku projektowego:

related_docs: ["[[crm/kontakt-a-firma-a|CEO firmy A]]",
               "[[crm/kontakt-b-firma-a|Kontakt techniczny]]"]

Gdy pytasz o projekt albo klienta, taki zapis ułatwia szybkie odtworzenie powiązań między osobami, zadaniami i decyzjami.

Obsidian z kolei pozwala wizualizować te relacje - graf wiedzy o Twoich kontaktach, projektach i decyzjach. Ale sama korzyść z backlinków w plikach .md jest niezależna od Obsidiana - działa z każdym edytorem.

Obsidian CLI - agregacja bez pętli

Gdy masz 30 albo 300 plików i chcesz szybko wyciągnąć konkretny wycinek - zamiast czytać wszystko po kolei, używasz wyszukiwania po metadanych:

obsidian search query="stage: OFFER"

Tu też warto doprecyzować jedną rzecz: Obsidian CLI to nie jest wiedza powszechna i nie każdy ma to domyślnie w systemie. To oficjalny interfejs wiersza poleceń Obsidiana, dostępny w nowszych wersjach aplikacji. Trzeba go włączyć w ustawieniach Obsidiana (Settings -> General -> Command line interface) i zarejestrować w systemie. Z dokumentacji wynika też ważny caveat: wymaga odpowiedniej wersji Obsidiana i działającej aplikacji desktopowej.

To nie jest wymagane do zbudowania całego workflow. To jest po prostu wygodna warstwa nad vaultem, kiedy liczba plików zaczyna rosnąć i zwykłe ręczne przeklikiwanie przestaje mieć sens.

W praktyce często dostajesz wynik szybciej niż przy ręcznym przeklikiwaniu. Bez pętli, bez grep, bez własnych skryptów do prostych przypadków.

Krok 4 - agenci z rolami: specjalizacja zamiast generalisty

Jeden wielki prompt z instrukcjami dla wszystkich sytuacji to anty-pattern.

Zamiast tego: osobne pliki per rola, które Claude Code może dobrać automatycznie albo które możesz wywołać jawnie.

Przykładowa struktura:

.claude/agents/
  strateg.md    - decyzje strategiczne, priorytety, "co robić"
  operacje.md   - checklisty, wyjątki, procedury, statusy
  kreator.md    - treści, szkice, copy, warianty komunikacji
  analityk.md   - KPI, raporty, liczby, priorytety
  asystent.md   - follow-upy, porządkowanie zadań, przypomnienia

I teraz najważniejsze: to nie jest tylko moja prywatna konwencja nazewnicza. Claude Code faktycznie wspiera projektowych agentów jako pliki Markdown z frontmatterem w katalogu .claude/agents/.

Każdy agent powinien mieć:

jasno opisane kiedy go używać
minimalny zestaw uprawnień (tylko te narzędzia których potrzebuje)
specyficzny styl odpowiedzi

Przykład nagłówka pliku agenta:

---
name: crm
description: "Kontakty sprzedażowe, pipeline, follow-up, scoring - użyj gdy mowa
              o konkretnych osobach/firmach w procesie sprzedaży"
tools: Read, Write, Edit, Glob, Grep, Bash
---

Zawsze zacznij odpowiedź od: CRM online

Pilnuj pipeline, follow-upów i priorytetu najbliższego ruchu. Jeśli brakuje danych, najpierw wskaż czego nie wiesz.

To nie musi być agent CRM. U księgowego to może być agent do rozliczeń i terminów. U grafika agent do feedbacku i assetów. U specjalisty SEO agent do content planu, audytów i priorytetów. Mechanika jest identyczna: AI dostaje wąską rolę, konkretny zakres i właściwy kontekst.

Ważny caveat: nie każdy kontekst nadaje się do wrzucenia do AI

To jest moment, który łatwo pominąć, a nie powinien wypaść z finalnego tekstu.

Sam fakt, że możesz zbudować taki system, nie znaczy jeszcze, że powinieneś wrzucać do niego dowolne dane. Jeśli pracujesz na danych klientów, dokumentach księgowych, danych osobowych, umowach albo wewnętrznych materiałach firmy, najpierw sprawdź politykę bezpieczeństwa, zasady przetwarzania danych i to, gdzie faktycznie trafia kontekst.

Dobra zasada na start jest prosta:

do eksperymentów używaj danych syntetycznych albo zanonimizowanych,
dane produkcyjne wrzucaj dopiero wtedy, gdy masz na to zgodę organizacji i rozumiesz model przetwarzania,
jeśli nie masz pewności, czy dany materiał można wkleić do narzędzia AI, traktuj to jako “nie” do momentu wyjaśnienia.

Jak ci agenci aktywują się w praktyce

To jest kluczowe, bo bez tego czytelnik nie wie, czy ma kopiować same pliki, czy jeszcze budować wokół nich własną orkiestrację.

W Claude Code masz kilka trybów uruchamiania agentów:

automatyczna delegacja - Claude sam wybiera agenta na podstawie Twojego polecenia i pola description,
jawne wywołanie w promptcie - możesz po prostu napisać “użyj agenta strateg do oceny tego pomysłu”,
@-mention - możesz wskazać konkretnego agenta wprost,
cała sesja jako agent - przez claude --agent nazwa-agenta albo ustawienie agent w .claude/settings.json.

Czyli: tak, Claude Code potrafi automatycznie delegować zadania do agentów na podstawie opisu zadania i pola description. Ale jeśli zależy Ci na przewidywalności, jawne wywołanie jest lepsze niż liczenie na zgadywanie.

Dobra praktyka jest prosta:

auto-delegację zostaw do oczywistych zadań,
jawnie wywołuj agentów tam, gdzie koszt pomyłki jest większy,
opis agenta traktuj jak kontrakt, nie jak ozdobę.

Krok 5 - hooki: automatyzacja wokół sesji i narzędzi

Hooki w Claude Code uruchamiają się automatycznie przy określonych zdarzeniach. Mogą wywoływać komendę, endpoint HTTP, prompt albo agenta - nie są ograniczone tylko do skryptów shellowych.

Przykładowy briefing-prep.ps1 może uruchamiać się na początku sesji i przygotowywać briefing albo dodatkowy kontekst z:

otwartymi zadaniami
rzeczami po terminie
najważniejszymi KPI albo checkpointami na dziś

Schemat hooka w settings.json:

{
  "hooks": {
    "SessionStart": [
      {
        "hooks": [{ "type": "command", "command": "scripts/pre-tool-check.ps1" }]
      }
    ],
    "SessionEnd": [
      {
        "hooks": [{ "type": "command", "command": "scripts/session-close.ps1" }]
      }
    ]
  }
}

I znowu ważne doprecyzowanie: ten plik nie wisi w próżni. Dla projektu najczęściej chodzi o .claude/settings.json. Jeśli chcesz lokalne, niecommitowane eksperymenty tylko dla siebie, używasz .claude/settings.local.json. Dla ustawień globalnych we wszystkich projektach jest jeszcze ~/.claude/settings.json.

Hook SessionEnd odpala się przy zamknięciu sesji. To dobre miejsce na cleanup, logowanie albo zapisanie podsumowania.

Efekt może być taki, że Claude dostaje na starcie dodatkowy briefing do kontekstu albo że w projekcie aktualizuje się plik z podsumowaniem stanu pracy.

To też nie jest feature “obok” Claude Code. Hooki są oficjalnym mechanizmem lifecycle events w ustawieniach. Innymi słowy: nie doklejasz hacka do modelu, tylko podpinasz skrypty do zdarzeń narzędzia.

Jeśli chcesz zacząć bez komplikacji, nie buduj od razu całego systemu eventów. Wystarczy jeden hook, który robi jedną rzecz dobrze: dodaje kontekst na SessionStart, waliduje komendy na PreToolUse albo robi cleanup na SessionEnd.

Jak to ewoluowało - od pliku .txt do grafu wiedzy

Nikt nie zaczyna od pełnej architektury. Zaczyna się od jednego pliku.

Etap 1 - jeden context.txt z kilkoma zdaniami o swojej pracy. Już to zwykle daje zauważalnie lepsze odpowiedzi.

Etap 2 - podział na pliki per temat. goals.md, tasks.md, contacts.md. Porządek zamiast jednej masy tekstu.

Etap 3 - frontmatter. Każdy plik zaczął mieć metadane. System zaczął lepiej rozróżniać rolę notatek i ich relacje.

Etap 4 - Obsidian jako warstwa wizualna i backlinki. Graf wiedzy zamiast katalogu plików.

Etap 5 - agenci i hooki. Automatyzacja i specjalizacja.

Etap 6 (w trakcie) - lokalny RAG. Gdy plików jest za dużo nawet dla frontmattera - vector search po całym vault.

Każdy krok daje zauważalną różnicę. Ale największy skok zwykle jest przy kroku pierwszym, bo wtedy AI przestaje zgadywać podstawy.

Gdzie ten system zaczyna kosztować za dużo

To jest moment, o który praktyk pyta od razu: “czy to nie zjada tokenów szybciej, niż daje wartość?”

Krótka odpowiedź: zjada, jeśli pomylisz strukturę wiedzy z ładowaniem wszystkiego naraz.

Najdroższy możliwy workflow wygląda tak:

trzymasz dziesiątki plików,
każesz agentowi czytać je wszystkie przy każdym zadaniu,
liczysz, że model sam wyłowi co ważne.

To jest zły system nie dlatego, że model jest za słaby, tylko dlatego, że pipeline retrieval jest leniwy.

Sensowny workflow wygląda odwrotnie:

CLAUDE.md niesie tylko stały kontekst i zasady,
frontmatter pomaga szybko zrozumieć rolę pliku,
hook, skrypt albo CLI wybiera tylko mały podzbiór notatek,
dopiero ten podzbiór trafia do pracy operacyjnej.

Nie podam Ci jednej uniwersalnej liczby plików albo tokenów, po której system “przestaje się opłacać”, bo to zależy od długości notatek, modelu i stylu pracy. Ale są trzy czytelne sygnały ostrzegawcze:

zanim dojdziesz do właściwego zadania, agent spędza czas głównie na czytaniu kontekstu,
rośnie latency, a odpowiedzi są coraz mniej stabilne,
łapiesz się na tym, że wiele notatek jest wczytywanych regularnie, choć realnie używasz z nich dwóch akapitów.

Wtedy nie potrzebujesz “większego modelu”. Potrzebujesz lepszego retrievalu. I właśnie wtedy RAG albo lepsza warstwa selekcji zaczynają mieć sens.

Co dalej testuję: lokalny RAG

Gdy vault rośnie do setek plików, nawet frontmatter przestaje wystarczać. Lokalny RAG (Retrieval-Augmented Generation) to następny krok.

Zamiast AI czytającego konkretne pliki - AI które pyta bazę wektorową “co wiem o Firmie A?” i dostaje top-5 najbardziej relevantnych fragmentów.

Da się zbudować wariant lokalny, z własnym indeksem i semantycznym wyszukiwaniem po historii sesji, decyzjach i notatkach. Ale to jest dokładnie ten moment, w którym trzeba bardzo świadomie rozumieć architekturę, prywatność i przepływ danych, zamiast zakładać je z automatu.

Na tym etapie to wciąż eksperyment. Warto go robić dopiero wtedy, gdy prostszy system naprawdę zaczyna pękać.

Zacznij od tego - template na start

Nie musisz budować całego systemu naraz. Jeden plik wystarczy żeby poczuć różnicę.

Utwórz CLAUDE.md w katalogu swojego projektu i wklej:

# Kontekst projektu

## Co budujemy
[opis projektu w 2-3 zdaniach]

## Stack techniczny
[język, framework, baza danych, deployment]

## Zasady których przestrzegamy
- [konwencja 1]
- [konwencja 2]
- nigdy nie rób [X] bo [dlaczego]

## Aktualny stan
[co działa, co jest w trakcie, co jest broken]

## Styl pracy z AI
- odpowiedzi krótkie i konkretne
- pytaj gdy nie wiesz zamiast zgadywać
- flaguj ryzyka zanim zaczniesz implementować

Otwórz Claude Code w tym katalogu. Różnicę zobaczysz przy pierwszym pytaniu, niezależnie od tego czy zarządzasz sprintem, zamknięciem miesiąca, projektami klientów czy listą publikacji.

Stan na kwiecień 2026: część opisanych tu funkcji szybko ewoluuje, więc przed wdrożeniem warto sprawdzić aktualne docs Claude Code i Obsidiana zamiast traktować ten tekst jak niezmienną specyfikację.

Jeśli chcesz podejść do tego bezpiecznie, kolejność wdrożenia jest prosta:

najpierw samo CLAUDE.md,
potem porządek katalogów,
dopiero później agenci,
na końcu hooki i wyszukiwanie po vaultcie.

To dobra kolejność nie dlatego, że brzmi metodycznie, tylko dlatego, że każdy kolejny etap dokłada złożoność operacyjną. Najpierw sprawdź, czy naprawdę masz problem z kontekstem. Dopiero potem buduj system, który ma ten problem obsłużyć.

Podsumowanie

AI świetnie odpowiada na pytanie “JAK?”. Ale dalej człowiek musi wiedzieć “CZY?” i “PO CO?”.

Ten system nie jest tylko dla jednej branży. To wzorzec pracy z AI dla każdego, kto działa na zadaniach, decyzjach, terminach i kontekście.

System nie zastępuje myślenia - daje mu lepsze paliwo. Im lepszy kontekst, tym mniej czasu tracisz na tłumaczenie, a więcej na rzeczywistą pracę.

I nie oddawaj mu sterów nad architekturą. Pozwól mu wiosłować.

EfektywnyDev pisze o AI w praktyce, architekturze pracy i systemach, które mają działać w realnym świecie, a nie tylko dobrze wyglądać w demie.