Cały kontekst pracy, projekty, klientów, decyzje i lekcje, trzymam w plikach Markdown w jednym repozytorium. Agent czyta je na starcie każdej sesji, zapisuje decyzje w trakcie i zostawia prompt na następną sesję. Nic nie żyje w czacie.
All my working context, projects, clients, decisions and lessons, lives in Markdown files in one repository. The agent reads them at the start of every session, writes down decisions along the way and leaves a prompt for the next session. Nothing lives in the chat.
Każda decyzja, każdy fakt od klienta, każda lekcja trafia do pliku w trakcie sesji, nie na koniec. Czat jest ulotny, plik ma datę, autora i historię zmian.
Every decision, every fact from a client, every lesson goes into a file during the session, not at the end. Chat is fleeting, a file has a date, an author and a change history.
Rzeczywistość bije dokumentację. Wśród dokumentów najpierw instrukcje główne, potem mapa projektów, potem pamięć. Gdy dwa pliki się nie zgadzają, wygrywa wyższy, i to jest spisane.
Reality beats documentation. Among documents, the main instructions come first, then the project map, then memory. When two files disagree, the higher one wins, and that is written down.
Agent nie szuka po omacku. Instrukcje główne dostaje od narzędzia sam z siebie, więc pierwsza komenda, którą piszę, to przeczytanie mapy projektów. Z niej trafia do właściwego folderu i do ostatniego stanu. Bez tego zgaduje. Otwiera nie ten folder, pracuje na stanie sprzed tygodnia i dopisuje do tego wnioski. Przekonałem się na własnej skórze, stąd ta reguła.
The agent doesn't search blindly. The tool loads the main instructions on its own, so the first command I type is to read the project map. From there it goes to the right folder and to the last state. Without the router the agent guesses. It opens the wrong folder, works from a week-old state and draws conclusions on top of it. I learned that the hard way, hence the rule.
Jedno repozytorium git, prywatne. Struktura jest ta sama dla produktu, dla klienta i dla badania rynku, dlatego agent nie musi się uczyć nowego układu przy każdym temacie.
One git repository, private. The structure is the same for the product, for a client, and for market research, so the agent doesn't have to learn a new layout for every topic.
.claude/ ├── CLAUDE.md kim jestem, zasady pracy, tabela "słowo → który plik czytać" ├── projekt/ │ ├── STRUKTURA.md router #0: mapa projektów (aktywne / narzędzia / wstrzymane / zamknięte) │ ├── CLAUDE-REFERENCE.md procedury: deploy, kopie, weryfikacja UI, klucze (gdzie, nie jakie) │ └── sessions/ │ ├── <projekt>/ │ │ ├── MASTER-STATUS.md stan: identyfikacja, decyzje, pipeline, Last / Next │ │ ├── WIKI.md co to jest, słownik, decyzje architektoniczne │ │ ├── CONTINUATION-<data>.md prompt do wklejenia w nowej sesji: stan, zadania, bramki │ │ ├── SKRZYNKA-TERMINALI.md poczta między oknami pracującymi nad tym samym │ │ ├── docs/ research/ transkrypcje/ correspondence-*.txt │ │ └── leads/<firma>/ to samo, poziom niżej: jeden folder na jedną rozmowę z firmą │ └── ... kolejne foldery: produkt, klienci, badania rynku, narzędzia ├── memory/ jeden plik = jeden fakt, nagłówek: typ, opis │ ├── MEMORY.md indeks, jedna linia na fakt, ładowany do każdej sesji │ └── feedback-*.md user-*.md project-*.md reference-*.md ├── agents/ skills/ hooks/ role z modelem, metody, skrypty strażników wpięte w ustawienia └── .git pełna historia zmian, każdy commit z opisem po ludzku
.claude/ ├── CLAUDE.md who I am, working rules, a table "word → which file to read" ├── projekt/ │ ├── STRUKTURA.md router #0: project map (active / tools / paused / closed) │ ├── CLAUDE-REFERENCE.md procedures: deploy, backups, UI checks, keys (where, not what) │ └── sessions/ │ ├── <project>/ │ │ ├── MASTER-STATUS.md state: who the client is, decisions, pipeline, Last / Next │ │ ├── WIKI.md what it is, glossary, architecture decisions │ │ ├── CONTINUATION-<date>.md prompt to paste into a new session: state, tasks, gates │ │ ├── SKRZYNKA-TERMINALI.md mail between windows working on the same thing │ │ ├── docs/ research/ transkrypcje/ correspondence-*.txt │ │ └── leads/<company>/ the same, one level down: one folder per conversation with a company │ └── ... further folders: product, clients, market research, tools ├── memory/ one file = one fact, header: type, description │ ├── MEMORY.md index, one line per fact, loaded into every session │ └── feedback-*.md user-*.md project-*.md reference-*.md ├── agents/ skills/ hooks/ roles with a model, methods, guard scripts wired into the settings └── .git full change history, every commit with a human-readable description
The file names are the real ones, in Polish where I named them in Polish.
Krótki plik, poniżej dwustu linii, bo powyżej agent zaczyna gubić własne zasady. Kim jestem, jak ze mną pracować, zasady (spec przed kodem, przegląd człowieka przed scaleniem, commit za zgodą), i tabela, która mówi agentowi, jakie słowo w moim poleceniu oznacza, który plik ma otworzyć. Słowo "wdrożenie" ładuje stan wdrożenia, nazwa klienta ładuje jego folder. Agent nie zgaduje.
A short file, under two hundred lines, because above that the agent starts losing its own rules. Who I am, how to work with me, the rules (spec before code, human review before merge, commit only when I say so), and a table that tells the agent which word in my request means which file to open. The word "deployment" loads the deployment state, a client's name loads their folder. The agent doesn't guess.
Tabela wszystkich projektów, ze ścieżką, jednym zdaniem o czym, miejscem stanu i bramką. Osobno aktywne, narzędzia, wstrzymane i zamknięte, z powodem zamknięcia i lekcją. Ten plik czyta się jako pierwszy w każdej sesji i to on zatrzymuje dryf między tematami.
A table of every project, with the path, one sentence on what it is, where the state lives and what the gate is. Separately active, tools, paused and closed, with a reason for closing and a lesson. This file is read first in every session, and it's what stops drift between topics.
MASTER-STATUS to jeden plik z tym, co wiemy, co postanowiliśmy i kiedy, co jest w toku i co dalej. Pod nim badania, transkrypcje rozmów, korespondencja z datami, dokumenty. Dla rozmowy z firmą to samo, folder niżej, czyli brief, przygotowanie do spotkania, oferta, draft umowy, log wiadomości. Ktokolwiek wejdzie do folderu, wie, na czym stoimy.
MASTER-STATUS is one file with what we know, what we decided and when, what's in progress and what's next. Below it, research, call transcripts, dated correspondence, documents. For a conversation with a company, the same thing one level down, meaning brief, meeting prep, offer, draft contract, message log. Whoever opens the folder knows where things stand.
Nie historia projektu, tylko fakty, które mają przetrwać projekty. Kim jestem i jak lubię pracować, poprawki, które mi dał człowiek ("nie usuwaj masowo, proponuj"), stałe ustalenia, odnośniki. Pamięć faktów jest wbudowana w narzędzie, jeden plik na fakt i indeks ładowany do każdej sesji. Domyślnie zostaje na jednym komputerze, więc trzymam ją w repozytorium i jedzie razem z resztą. Dopisałem do niej jedną rzecz, której narzędzie nie daje, czyli regułę, że fakt obalony się kasuje, a nie poprawia w nieskończoność.
Not a project history, just facts meant to outlive projects. Who I am and how I like to work, corrections a human gave me ("don't mass-delete, propose"), standing decisions, references. The fact memory is built into the tool, one file per fact and an index loaded into every session. By default it stays on one machine, so I keep it in the repository and it travels with everything else. I added one thing the tool does not give, the rule that a fact proven wrong gets deleted rather than patched forever.
Sesja ma początek, środek i koniec, i każdy z nich zostawia ślad w plikach. Następna sesja startuje od pliku, który zostawiła poprzednia, nie od mojej pamięci.
A session has a beginning, a middle and an end, and each of them leaves a trace in the files. The next session starts from the file the previous one left, not from my memory.
Wklejam prompt, który zostawiła poprzednia sesja. Agent czyta mapę projektów, potem folder, potem ostatni stan.
I paste in the prompt the previous session left. The agent reads the project map, then the folder, then the last state.
Decyzja pada, decyzja idzie do pliku, z datą. Fakt od klienta idzie do logu korespondencji. Większa robota idzie jako brief do innego okna, wraca jako raport. Spec zanim kod, czyli problem, czego nie robimy, kryteria akceptacji. Testy piszę z tych kryteriów, więc spec jest jednocześnie listą rzeczy do sprawdzenia.
A decision is made, the decision goes into a file, with a date. A fact from a client goes into the correspondence log. Bigger work goes to another window as a brief and comes back as a report. Spec before code, meaning the problem, the non goals and the acceptance criteria. I write the tests from those criteria, so the spec doubles as the checklist.
Aktualizacja stanu, prompt na następną sesję, wpis do skrzynki dla innych okien, commit z opisem po ludzku, push.
State update, a prompt for the next session, an entry in the mailbox for other windows, a commit with a human-readable message, push.
Nad jednym tematem pracuje kilka okien, jedno strategiczne (plan dnia, decyzje), jedno wykonawcze (kod, dokumenty), czasem osobne do badań. Okna mają rozdzielone role i rozdzielone pliki, żeby nie wchodziły sobie w edycje. Nie dzielą pamięci, więc dostały pocztę, plik skrzynki w folderze projektu. Wpis ma dwie do pięciu linii, datę, nadawcę, co się stało i gdzie leży szczegół. Adresat dopisuje status. Duże rzeczy idą osobnym plikiem, brief w jedną stronę, raport w drugą, skrzynka tylko wskazuje. Narzędzie ma dziś własny kanał między sesjami i czasem go używam, ale trwały ślad zostaje w pliku. Wiadomość znika razem z sesją, wpis w repozytorium przeczyta jutro ktokolwiek.
Several windows work on one topic, one strategic (day plan, decisions), one for execution (code, documents), sometimes a separate one for research. The windows have separate roles and separate files, so they do not step on each other's edits. They don't share memory, so they got mail, a mailbox file in the project folder. An entry is two to five lines, a date, a sender, what happened and where the detail lives. The recipient adds a status. Bigger things go as a separate file, a brief one way, a report the other, the mailbox just points to it. The tool now has its own channel between sessions and I use it sometimes, but the lasting record stays in a file. A message disappears with the session, an entry in the repository can be read tomorrow by anyone.
Jedna zasada nie ustępuje. Decyzje podejmuje wyłącznie człowiek. Agent zatrzymuje się i pyta przed commitem, przed wdrożeniem, przed każdą wiadomością na zewnątrz i przed zmianą własnych zasad. Skrzynka przenosi informacje o decyzjach, z datą, nigdy ich nie tworzy. Gdy dwa wpisy się przeczą, wygrywa nowsza decyzja człowieka.
One rule does not bend. Only a human makes decisions. The agent stops and asks before a commit, before a deploy, before any message that leaves the repository and before changing its own rules. The mailbox carries information about decisions, with a date, it never creates them. When two entries disagree, the newer human decision wins.
Sesja główna to najmocniejszy model Claude w roli lidera technicznego. Osąd, spec, przegląd wyników, dokumenty. Wykonanie idzie do agentów z przypiętym modelem, dobranym do zadania (model routing). Podział jest prosty. Osąd zostaje u najmocniejszego modelu, mechanika idzie tam, gdzie jest tańsza i szybsza. Powód jest twardszy niż koszt. Każdy agent pracuje we własnym oknie i oddaje streszczenie, więc przeszukanie stu plików nie zajmuje miejsca w sesji, która podejmuje decyzje.
The main session is the strongest Claude model in the role of technical lead. Judgment, spec, review of results, documents. Execution goes to agents with a model pinned to them, matched to the task (model routing). The split is simple. Judgment stays with the strongest model, mechanical work goes where it is cheaper and faster. The reason is harder than cost. Each agent works in its own window and returns a summary, so reading a hundred files does not take up room in the session that makes the decisions.
| Rola | Model | Do czego | Czego nie robi |
|---|---|---|---|
| Sesja główna | Fable, najmocniejszy | spec, decyzje architektoniczne, przegląd kodu i raportów, teksty do klienta, synteza | nie klepie mechaniki, nie przeczesuje repozytorium |
| Reasoner | Opus, mocny | trudna logika, migracje, integracje, wieloetapowe debugowanie | nie podejmuje decyzji o architekturze |
| Worker | Sonnet, szybki | szablony, testy z gotowych kryteriów, fixtures, transformacje plików | nie zgaduje, dostaje dokładny brief |
| Scout | Haiku, najtańszy | przeszukiwanie kodu i plików, inwentaryzacje, zbieranie cytatów | tylko czyta, nic nie zmienia |
| Role | Model | What for | What it doesn't do |
|---|---|---|---|
| Main session | Fable, strongest | spec, architecture decisions, reviewing code and reports, client-facing text, synthesis | doesn't do mechanical work, doesn't crawl the repository |
| Reasoner | Opus, strong | hard logic, migrations, integrations, multi-step debugging | doesn't make architecture decisions |
| Worker | Sonnet, fast | templates, tests from ready criteria, fixtures, file transformations | doesn't guess, gets an exact brief |
| Scout | Haiku, cheapest | searching code and files, inventories, gathering quotes | read only, changes nothing |
Do tego metody, czyli skille. Panel ekspertów do decyzji (kilka person debatuje nad ofertą, a ja siedzę przy stole i odpowiadam na ich pytania), przegląd kodu, testy end-to-end, zamknięcie sesji. Oraz oczy. To, co powtarzalne, sprawdza Playwright, testy end-to-end w CI i zrzuty do przeglądu. Gdy stan istnieje tylko u mnie, agent dostaje most do mojej przeglądarki (Claude in Chrome), klika po aplikacji i robi zrzuty, każde działanie ze skutkiem zatwierdzam ręcznie, a werdykt daję ze zrzutu, nie z zielonego testu. Zielony test nie widzi tekstu, który stracił sens.
On top of that there are methods, skills. An expert panel for decisions (a few personas debate an offer, and I sit at the table answering their questions), code review, end-to-end tests, closing a session. And eyes. Whatever is repeatable is checked by Playwright, end-to-end tests in CI and screenshots for review. When the state exists only on my machine, the agent gets a bridge to my browser (Claude in Chrome), clicks around the app and takes screenshots, I approve every action with consequences by hand, and I give the verdict from the screenshot, not from a green test. A green test doesn't see text that has lost its meaning.
System oparty na plikach bez strażników rozjeżdża się w miesiąc. To hooki Claude Code, czyli skrypty, które narzędzie odpala samo, przed komendą albo przy zamykaniu sesji. Uruchamia je narzędzie, nie model, więc nie wystarczy, żeby agent uznał, że tym razem nie trzeba. Powstały z researchu, jak inni pracują na tym narzędziu, z dokumentacji i z własnej praktyki.
A system built on files drifts apart within a month without guards. These are Claude Code hooks, scripts the tool runs on its own, before a command or when a session closes. The tool runs them, not the model, so it is not enough for the agent to decide that this time they do not apply. They came from research into how others work with this tool, from the documentation and from my own practice.
Nic egzotycznego. Laptop, terminal, przeglądarka, prywatny git, jeden serwer z kontenerami i kopie zapasowe. Agent ma dostęp do tego, do czego ja, z wyjątkiem kluczy, które widzi tylko jako nazwy.
Nothing exotic. A laptop, a terminal, a browser, private git, one server with containers, and backups. The agent has access to what I have, except for the keys, which it only sees as names.
Zasada przepływu. Edycja lokalnie, commit, push, dopiero potem wdrożenie skryptem. Na serwerze nie zmieniam nic ręcznie, nawet przy pilnej poprawce, bo poprawka poza gitem znika przy następnym wdrożeniu i za tydzień nikt nie wie, czemu problem wrócił. Skrypt robi kopię, podmienia wersję i umie ją wycofać jednym poleceniem.
Flow rule. Edit locally, commit, push, only then deploy by script. I change nothing by hand on the server, not even for an urgent fix, because a fix outside git disappears at the next deploy and a week later nobody knows why the problem came back. The script takes a backup, swaps the version and can roll it back with one command.
Zbudowałem też agentowi pamięć semantyczną. Baza wektorowa, otwarty model osadzeń uruchomiony u siebie, potok badań, zapis sesji z oceną jakości i deduplikacją. Wiem, jak to działa od środka, i wiem, kiedy nie ma sensu. Baza wektorowa zarabia na siebie, gdy wiedzy jest więcej, niż mieści okno modelu, a pytania są rozmyte. Baza wiedzy dla handlowców, historia reklamacji, dokumentacja produktów. Notatki jednej osoby mieszczą się w oknie. Tam wygrywa plik z datą i autorem, bo kosztuje zero i czyta go człowiek. Dlatego wyżej są pliki, nie wektory.
I also built semantic memory for an agent. A vector database, a self hosted open embedding model, a research pipeline, session capture with quality scoring and deduplication. I know how it works from the inside, and I know when it makes no sense. A vector database earns its keep when there is more knowledge than fits in the model window and the questions are fuzzy. A knowledge base for sales, complaint history, product documentation. One person's notes fit in the window. There a file with a date and an author wins, because it costs nothing and a human can read it. That is why what you see above is files, not vectors.
Konkretnie. Trzy osie metadanych na każdym fragmencie, domena, projekt i etap życia, z indeksami pod filtrowanie, żeby pytanie o wdrożenie u jednego klienta szło po filtrze, nie tylko po podobieństwie. Jeden punkt zapisu przez API z kluczem, a w nim cięcie na fragmenty z zakładką, deduplikacja po skrócie treści i ocena jakości modelem na wejściu, żeby śmieci nie trafiały do indeksu. Osiem typów źródeł, od researchu po zapis sesji. Wyszukiwanie wystawione agentowi przez serwer MCP i lista sprawdzonych zapytań na start, żeby nie zgadywał słów. Dwie kolekcje, osobno wiedza projektowa, osobno baza wiedzy dziedzinowej.
Concretely. Three axes of metadata on every chunk, domain, project and lifecycle stage, with indexes for filtering, so that a question about one client's deployment goes through a filter, not just through similarity. One write path through an API with a key, and inside it chunking with overlap, deduplication by content hash and a quality score from a model on the way in, so that junk never reaches the index. Eight source types, from research to session capture. Search exposed to the agent through an MCP server, plus a list of proven queries to start from, so it does not guess the words. Two collections, project knowledge and a domain knowledge base kept apart.
Wchodzę z gotowym warsztatem. Instrukcje agenta, role modeli, strażnicy komend i sekretów, przekazywanie sesji przez pliki. Powstał dla jednej osoby, więc w zespole najpierw sprawdzam, co przeżyje kontakt z cudzymi opiniami. Dokładam to do tego, co zespół już ma, jako pliki obok kodu, w formacie, który czyta większość narzędzi, zmieniane przez PR, i zostaje tyle, ile zespół uzna za przydatne.
I arrive with a toolkit that already works. Agent instructions, model roles, command and secret guards, session handover through files. It was built for one person, so in a team I first check what survives contact with other people's opinions. I fit it to what the team already has, as files next to the code, in the format most tools read, changed through PRs, and what stays is what the team finds useful.
Piszę pod następną osobę. Nie zostawiam po sobie wiedzy do przekazania ustnie, więc przejęcie projektu ode mnie nie wymaga ani mojej obecności, ani mojego kalendarza.
I write for the next person. I leave behind nothing that has to be handed over in conversation, so taking a project over from me needs neither my presence nor my calendar.
Mierzę, zanim uwierzę. Model, narzędzie albo baza wchodzą do systemu po benchmarku na prawdziwych danych i wychodzą, gdy logi pokazują, że nikt z nich nie korzysta.
I measure before I believe. A model, a tool or a database enters the system after a benchmark on real data and leaves when the logs show nobody uses it.
Tak pracuję. Projekty i kontakt są na stronie głównej. Napisz na piotr.sobczak@odok.pl.
This is how I work. Projects and contact are on the home page. Write to piotr.sobczak@odok.pl.