Analityka agentowa to coś więcej niż tekst-do-SQL: lekcje z doświadczeń Anthropic
Co mówi artykuł o analityce samobieżnej Anthropic na temat warstw semantycznych, umiejętności, ocen i podstaw danych oraz dlaczego sama funkcja tekst-do-SQL daje fałszywe wrażenie precyzji.
Źródła: Anthropic is telling you that Agentic Analytics is not just text-to-SQL
„Slop” w analityce to nowy „slop” w AI
Post z 3 czerwca 2026 roku od Anthropic na temat analityki samousługowej mówi publicznie to, czego wiele zespołów zajmujących się danymi nauczyło się na własnych błędach: analityka oparta na agentach nie jest tym samym co kierowanie narzędzia Claude Code w stronę bazy danych i zadawanie mu pytań.
Większość ludzi zna termin „slop” w AI. „Slop” w analityce jest jego odpowiednikiem. Dzięki agentom programistycznym każdy może teraz łączyć się z bazą danych i tworzyć raporty analityczne. To świetnie obniża bariery wejścia, ale z drugiej strony prawie nikt nie sprawdza tych danych. Karty informacyjne przychodzą w postaci plików .html, stron w Confluence lub zrzutów ekranu terminala, a niewiele z nich zostało zweryfikowanych. Powodem jest fałszywe poczucie bezpieczeństwa – skoro modele językowe tak dobrze przekładają angielski na SQL, odpowiedzi muszą być poprawne, takie jest przekonanie.
To zaufanie jest nieuzasadnione. Gdy analityka oparta na agentach sprowadza się do generowania zapytań, problem jest postrzegany zbyt wąsko, a otaczająca go infrastruktura pozostaje niezauważona, mimo że to ona decyduje o tym, czy dane odpowiedzi są pomocne, czy szkodliwe. Sam projekt Anthropic umieszcza fundamenty danych, źródła prawdy, umiejętności oraz procesy weryfikacji przed momentem, w którym Claude widzi jakiekolwiek zapytanie. Artykuł wymienia klasyczne praktyki inżynierii danych jako obowiązkowe wymagania i przekazuje wskazówki, dzięki którym inne zespoły mogą uniknąć tych samych błędów.
To artykuł z serii Enterprise AI, a nie praca badawcza, ale jest to jeden z najjaśniejszych opisów praktycznych aspektów tworzenia wiarygodnej analityki agentowej. W tekście omawiane są kolejno główne koncepcje: dlaczego podejście typu text-to-SQL jest błędne, skąd pochodzi niejednoznaczność, co stworzyła firma Anthropic, co musi istnieć przed napisaniem zapytania, rola warstwy semantycznej i umiejętności modelu, dlaczego ważne są oceny i konserwacja, oraz od czego zespół powinien zacząć.
Dlaczego text-to-SQL przyciąga całą uwagę
Generowanie zapytań to ta część, którą można zademonstrować w ciągu trzydziestu sekund. Zadaj pytanie prostym językiem angielskim, obserwuj, jak model tworzy zapytanie, uruchamia je w bazie danych i otrzymuje wynik w postaci liczby lub wykresu. Wygląda to magicznie, szczególnie dla osób niebędących specjalistami technicznymi, które wcześniej polegały na zespołach analitycznych lub gotowych panelach kontrolnych.
Jasne wyjaśnienie oraz schludna liczba podana przez Claude’a lub Codex nie mówią nic o tym, czy pytanie zostało poprawnie odpowiedziane. Według Anthropicu skierowanie Claude’a na konkretny magazyn może stworzyć fałszywe wrażenie precyzji, a to właśnie jest pułapka.
Weźmy na przykład osobę zainteresowaną, która pyta: „Jaki był przychód od aktywnych klientów w zeszłym miesiącu?”. Już tutaj pojawiają się subtelności analityczne:
- Co sprawia, że klient jest uznawany za aktywnego?
- Która definicja klienta jest oficjalna?
- Czy chodzi o przychód brutto, czy netto?
- Które pole daty ma zastosowanie?
- Które zwroty, filtry oszustw lub wykluczenia produktów powinny zostać uwzględnione?
Tłumaczenie tekstu na SQL następuje dopiero po podjęciu tych decyzji. Dlatego niezawodny agent analityczny potrzebuje całej infrastruktury, która kieruje jego rozumieniem biznesu.
To nawiązuje do dobrze znanej pracy Google na temat ukrytego długu technicznego w systemach uczenia maszynowego, która pokazała, że model stanowi małą skrzynkę w ramach znacznie większego aparatu produkcyjnego uczenia maszynowego.
Rysunek powyżej to zrzut ekranu z tej pracy. Ten sam obraz odnosi się również do agentów analitycznych, jeśli małą czarną skrzynkę zastąpi się narzędziem text-to-SQL.
Odpowiedź Anthropic pasuje do tego ujęcia, jak w zdaniu „Dane to nie oprogramowanie”. Praca analityczna zawodzi inaczej niż funkcje oprogramowania. Zazwyczaj istnieje jedna prawidłowa odpowiedź pochodząca z jednego poprawnego źródła, ale nie ma deterministycznego sposobu na jej potwierdzenie wyłącznie na podstawie końcowego wyniku. System może generować bezbłędny SQL, całkowicie pomijając przy tym znaczenie biznesowe.
Anthropic przedstawia również zestaw przykładów porównujących te dwa paradygmaty, pokazanych w poniższej tabeli.
Anthropic dzieli powstałe błędy na trzy kategorie:
- Ambiwalencja koncepcji lub entity. Użytkownik mówi „aktywni użytkownicy”, „przychód” lub „retencja”, a agent musi wybrać spośród kilku prawdopodobnych wariantów realizacji. Różnice są często na tyle subtelne, że błędna odpowiedź nadal wygląda profesjonalnie.
- Zastarzenie danych. Dokumentacja, tabele oraz zasady biznesowe ciągle się zmieniają. Wskaźnik, który był poprawny trzy tygodnie temu, może nagle stać się błędny po zmianie schematu, dodaniu nowej reguły wykluczenia lub przebudowie panelu kontrolnego.
- Niepowodzenie w wyszukiwaniu. Gdzieś w całym systemie istnieje prawidłowa odpowiedź, ale jest zbyt wiele materiałów do przeszukania. Model przeocza odpowiednią tabelę, wskaźnik lub dokument i z ufnością opiera się na czymś podobnym, ale błędnym.
Sam magazyn nie może rozwiązać żadnego z tych problemów. Przechowuje dane, a nie pełne znaczenie biznesu, które jest rozproszone pomiędzy definicjami metryk, modelami semantycznymi, zastrzeżeniami, konwencjami zespołu, odpowiedzialnościami i historią. W przykładzie z przychodami napisanie instrukcji GROUP BY jest proste. Trudno jest jednak określić, co oznacza „aktywny”: jedna zakupiona transakcja w ciągu trzydziestu dni, opłacona korzystanie bez oszustw w danym okresie rozliczeniowym, czy też próg specyficzny dla danej domeny, który istnieje wyłącznie w warstwie semantycznej.
Dlatego to, czy Claude potrafi pisać SQL, nie jest tak istotne, ponieważ prawdopodobnie robi to lepiej niż większość ludzi. Ważniejsze pytanie brzmi, co Anthropic musiało stworzyć wokół Claude’a, aby te problemy przestały dominować wynikami.
Co stworzyło Anthropic
Odpowiedź to połączenie sprawdzonej praktyki inżynieryjnej z dodatkowymi warstwami, które umożliwiają agenci. W rzeczywistości jest to kompletny system, w którym Claude pełni rolę interfejsu na górze, a wszystko inne znajduje się poniżej. Artykuł dzieli go na cztery części:
- Podstawy danych, czyli kanoniczne zbiory danych, modele danych, transformacje, testy, sprawdzanie aktualności oraz metadane.
- Źródła prawdy, obejmujące warstwę semantyczną, ścieżki pochodzenia danych, kontekst biznesowy oraz starannie wyselekcjonowane materiały referencyjne, które pomagają powiązać pytanie z określonym znaczeniem.
- Umiejętności, czyli procedury specyficzne dla danej dziedziny, które wskazują modelowi, jak pracować, a nie tylko to, jakie dane są dostępne.
- Walidacja, obejmująca oceny offline, sprawdzania online, śledzenie pochodzenia danych oraz pętle konserwacyjne.
Zdjęcie ekranu powyżej pochodzi z posta Anthropic. Zwróć uwagę na to, gdzie w sekwencji pojawia się SQL: po wszystkich trudnych decyzjach. Gdy model w końcu tworzy zapytanie, „stack” już zawęził znaczenie pytania oraz określił, który wybrany ścieżka zasługuje na zaufanie.
Taka struktura lepiej oddaje wartość podaną w nagłówku niż sama selekcja modelu. Szybkie przeczytanie sprawia, że liczba 95 procent brzmi jak wskaźnik wydajności modelu, natomiast uważniejsze przeczytanie pokazuje, że chodzi o wskaźnik wydajności systemu, biorąc pod uwagę to, jak dużo w tekście opisuje narzędzie używane z Claude’em, a jak mało samego Claude’a.
Czego musi być przed napisaniem jakiegokolwiek zapytania SQL
Anthropic jasno stwierdza, że nadal obowiązuje standardowa inżynieria danych: modelowanie wymiarowe, sprawdzanie świeżości i kompletności danych, gotowe do użycia zestawy danych kanoniczne oraz jasne słowniki danych. Nic z tego nie znika tylko dlatego, że interfejs stał się bardziej konwersacyjny. Wręcz przeciwnie – presja rośnie, ponieważ użytkownik jest teraz agentem działającym na podstawie pytania człowieka. Analityk czasami może wyczuć, że tabela jest nieprawidłowa, natomiast agent może znacznie szybciej doprowadzić do błędnych wniosków.
Istnieje pewna ironia w tym, że firma będąca pionierem mówi światu, iż dobra stara inżynieria danych jest niezbędna dla agentów. Żadna z tych praktyk nie jest nowa – każda książka o magazynowaniu danych sprzed dwudziestu lat daje te same zalecenia. Warto je jednak ponownie podkreślić.
Zestawy danych kanoniczne
Niewielka liczba ściśle regulowanych modeli logicznych, z których każdy stanowi jedyny źródło prawdy, zmniejsza liczbę prawdopodobnych odpowiedzi jeszcze przed rozpoczęciem wyszukiwania. Mogą być potrzebne różne poziomy agregacji, ale wszystkie one powinny czerpać dane z tej małej bazy. To samo dotyczy agentów analitycznych: gdy mogą uzyskać dostęp tylko do kilku zaufanych zbiorów danych i wiedzą, jak te dane odpowiadają wzbogaconym wymiarom, szansa na wybór niewłaściwego źródła znacznie spada.
Metadane jako produkt pierwszej klasy
Metadane dostarczają agentowi dokładnego opisu tabel, kolumn, struktury danych, osób odpowiedzialnych oraz ograniczeń. Jeśli nikt nie dokumentuje modelu, znaczenia poszczególnych kolumn ani kluczy łączących, model językowy AI wypełnia każdą lukę domysłami.
Trzymanie modeli, dokumentacji, paneli kontrolnych i plików z umiejętnościami razem
Colocation może oznaczać po prostu duże monorepo, ale Anthropic definiuje to bardziej precyzyjnie. Prawie cały kod związany z danymi – od modelowania i warstwy semantycznej po dokumentację oraz standardowe definicje paneli sterowania – znajduje się w jednym repozytorium, chronionym przez kontrole CI sprawdzające integralność między poszczególnymi warstwami. Każda zmiana w modelowaniu, która mogłaby uszkodzić panel sterowania lub unieważnić udokumentowaną miarę, jest wykrywana przez CI, a naprawa jest włączana do tej samej prośby o pull request.
To podważa błędne przekonanie, że analiza AI sprawia, że inżynieria danych traci na znaczeniu. Im więcej pytań przechodzi przez modele, tym bardziej widoczna staje się jakość warstwy modelowania.
Inni dostawcy również to pokazują. Warstwa semantyczna dbt istnieje po to, aby definicje metryk były pisane raz i wykorzystywane przez wszystkie narzędzia. Microsoft zaleca przygotowywanie danych do Power BI w celu użycia z Copilotem, stosując schematy gotowe do pracy z AI, zweryfikowane odpowiedzi oraz wyraźne instrukcje, dzięki czemu model może odpowiadać w oparciu o solidny kontekst. Snowflake buduje Cortex Analyst wokół modeli semantycznych i zweryfikowanych zapytań, z monitorowaniem kroku generowania SQL. Każdy produkt uczy tego samego: kontekst przygotowany z wyprzedzeniem jest częścią odpowiedzi.
Warstwa semantyczna to mapa agenta
Warstwa semantyczna to most architektoniczny, który przekształca surowe, złożone dane w znajome terminy biznesowe, wskaźniki i relacje. Znajduje się pomiędzy systemami przechowywania danych, takimi jak Snowflake, Databricks czy BigQuery, a narzędziami do ich wykorzystania, takimi jak Power BI, Tableau czy agenci AI. Dzięki niej można odpowiedzieć na pytania o znaczenie kolumny, typ innego elementu, sposób obliczania wskaźnika oraz funkcjonowanie hierarchii i relacji między tabelami.
Wykres powyżej pokazuje, gdzie znajduje się ta warstwa. Anthropic traktuje ją jako tak kluczową, że jej agenci są strukturalnie zobowiązani najpierw konsultować się z warstwą semantyczną. Zasada działania polega na tym, że model wychodzi od określonego znaczenia, a nie od bezkierunkowej eksploracji surowych tabel. Anthropic idzie jeszcze dalej i uważa za złą praktykę pozwalanie agentom samodzielnie tworzyć warstwę semantyczną. Ludzie pozostają niezbędni do jej utrzymania w dobrym stanie, a to pochodzi z jednego z czołowych laboratoriów na świecie.
Przemysł zmierza w tym samym kierunku. Narzędzie Cortex Analyst firmy Snowflake wykorzystuje model semantyczny do łączenia pytań biznesowych z strukturą bazy danych. Genie od Databricks polega na ekspertach z danej dziedziny, którzy dostarczają zestawy danych, instrukcje, przykłady kodu SQL oraz kontekst biznesowy. dbt przechowuje logikę pomiarów w jednym miejscu, dzięki czemu narzędzia późniejsze nie muszą jej ponownie budować, a Microsoft umieszcza zweryfikowane odpowiedzi oraz instrukcje AI w modelu BI. Agent ds. nauki o danych firmy Google potrzebował czegoś podobnego – warstwy pseudosemantycznej o nazwie Analyzer – zanim jego wyniki stały się użyteczne.
Bez takiej mapy agent tylko zgaduje. Z nią model skupia swoje wysiłki na rozumowaniu w określonym kontekście, zamiast tworzyć go od zera.
Przykładowe zapytania uzupełniają tę warstwę
Anthropic donosi, że zbiór zapytań, czyli historyczne zapytania SQL pochodzące z paneli kontrolnych, notatek i wcześniejszych analiz, może mieć pozytywny efekt netto. Skuteczne rozwiązanie polega nie na podawaniu mu surowych danych bez przetworzenia. Zamiast tego zbiór ten jest przerabiany na ustrukturyzowane dokumenty referencyjne dla poszczególnych dziedzin oraz wzorce analizy, które można ponownie wykorzystać w umiejętnościach. Historia zapytań stanowi surowiec do selekcji, a nie źródło prawdy, które agent odczytuje bezpośrednio.
Istnieje również praktyczna konsekwencja dotycząca tego, kto posiada co. Ponieważ agent analityczny opiera się na zdefiniowanych regułach, osoby odpowiedzialne za utrzymywanie tych definicji – zazwyczaj inżynierowie analityczni i właściciele domen – stają się częścią mechanizmu kontroli jakości agenta. Sporna metryka przestaje być przedmiotem kłótni na temat panelu sterowania i staje się błędem w wspólnym warstwie danych, który jest naprawiany w jednym miejscu i widoczny dla wszystkich użytkowników, zarówno ludzi, jak i modeli. Zespoły, które już tak pracują, będą postrzegać przejście na agenty jako mniej uciążliwe niż te, których logika metryk jest rozproszona pomiędzy notatkami i narzędziami BI.
Dlaczego umiejętności tak mocno wpływają na dokładność
Warstwa semantyczna wyjaśnia, co oznacza świat, ale nie pokazuje, jak w nim działać. Nie może określić, jakie kroki podejmuje dobry analityk, gdy interesariusz zadaje niejednoznaczne pytanie dotyczące dwóch potencjalnych źródeł danych oraz znanego przypadku wyjątkowego w określonym regionie.
W systemie analitycznym Anthropic umiejętności funkcjonują jak zakodowane instrukcje analityka, a nie jako dokumentacja. Zawierają one wiedzę proceduralną:
- porządek sprawdzania źródeł
- miejsce, w którym należy zastosować warstwę semantyczną, oraz miejsca, gdzie dopuszcza się rozwiązania awaryjne
- pytania uzupełniające, które należy zadać zaangażowanym stronom
- ograniczenia obowiązujące w danym obszarze
- sposób zweryfikowania wyniku przed zaufaniem mu
- szczegóły pochodzenia informacji, które trafiają do ostatecznej odpowiedzi
Największy sukces Anthropic wynika właśnie stąd. Zgodnie z sekcją poświęconą umiejętnościom w tym artykule, Claude nigdy nie osiągnął ponad 21 procent w ich ocenach analitycznych bez użycia umiejętności. Dzięki warstwie umiejętności dokładność ogólna wzrosła powyżej 95 procent, a w niektórych obszarach osiągnęła nawet około 99 procent.
To wartość określa, jak powinien być nazywany system. Jeśli największy skok wynika z proceduralnego kierownictwa, a nie z lepszej generacji zapytań SQL, to w istocie nie jest to produkt typu tekst do SQL. Jest to produkt do przeprowadzania analiz z możliwością wykonywania zapytań w jego ramach.
Pomaga również pamiętać, czym umiejętność nie jest. To nie jest dłuższy prompt systemu, ani zbiór przykładowych zapytań wklejonych do niego. Jest to utrzymywany artefakt z wersją, warunkiem aktywacji oraz zdefiniowaną procedurą, który jest ładowany wtedy, gdy jest to konieczne. Dzięki temu można go przejrzeć w ramach pull requesta, przetestować na zbiorze danych do oceny, a także łatwo usunąć, gdy zmieni się leżący u jego podstaw model danych.
Poniższy obrazek pokazuje szablon umiejętności używany przez Anthropic.
Wszystkie te elementy razem tworzą pełną definicję, a załącznik zawiera cały szablon.
Oceny i konserwacja mają takie samo znaczenie jak prompty
Nawet dobrze przygotowany agent analityczny z czasem traci swoją skuteczność. Gdy już istnieją warstwy semantyczne, starannie dobrane przykłady oraz umiejętności, kolejnym problemem staje się dewiacja: tabele się zmieniają, definicje przesuwają się, panele kontrolne są odbudowywane, a umiejętności przestają odpowiadać modelowi źródłowemu. Procedura, która wczoraj była poprawna, dziś staje się przestarzałym kontekstem.
Anthropic podaje wyraźny przykład: dokładność pracy offline spadła z około 95 procent do około 65 procent w ciągu zaledwie jednego miesiąca, zanim utrzymanie umiejętności zaczęto traktować jako problem inżynieryjny. Ta liczba sprawia, że utrzymanie systemu staje się wymogiem niezawodności, a nie dodatkową przyjemnością.
Analityka ma tu praktyczną cechę, mianowicie oceny mogą opierać się na prawdziwych wartościach, które każda poprawna procedura powinna odtworzyć. Gdy to zostanie zdefiniowane, wszystkie pozostałe parametry systemu można dostosować w oparciu o nie. Zespół może przetestować drugą wersję danej umiejętności przy użyciu Haiku, Sonnet lub Opus na kilku poziomach trudności, porównać dokładność i wybrać tę wersję, która najlepiej balansuje koszt z jakością – czy to oznacza wystarczającą dokładność przy niższym koszcie, czy najwyższą dokładność za wszelką cenę.
Zrozwinięty system analityczny jest testowany w określony sposób: przechowywane przypadki, wyraźne stwierdzenia oraz pętla zwrotna, która przepisuje instrukcje działania w momencie, gdy system popełnia błąd. Databricks ma podobną koncepcję w swojej dokumentacji Genie, która łączy w jedno inspekcję odpowiedzi, punkty odniesienia, zaufane zasoby oraz starannie przygotowane instrukcje.
Tutaj prompty mają mniejsze znaczenie, niż ludzie zwykle przypuszczają. Jakość wciąż jest ważna, ale przy słabej warstwie semantycznej, przestarzałych przykładach, zmieniających się umiejętnościach i braku ocen, żaden „heroiczny” prompt nie uratuje systemu na długo. Analiza typu agentic działa wtedy, gdy cały system jest zarządzany jak utrzymywany produkt, a nie wtedy, gdy model ma pełny dostęp i musi improwizować.
Gdzie zespół ds. danych może zacząć
Najlepszym punktem wyjścia jest najprostsza struktura, która może zadziałać, z stopniowym dodawaniem złożoności tylko tam, gdzie wyniki pokazują, że jest to opłacalne. Wskazówki Anthropic dotyczące tworzenia skutecznych agentów przedstawiają ten sam argument, a następny post o analizie potwierdza go. Oto pięć kroków:
- Wybierz jeden obszar, a nie cały zakres działalności – na przykład jakość przychodów, operacje wsparcia klienta, kanały wzrostu lub raportowanie finansowe. Wybierz dziedzinę z jasnym odpowiedzialnym i powtarzającymi się pytaniami.
Należy unikać łączenia nowoczesnego modelu bezpośrednio z systemem przechowywania danych i nazywania tego strategią. Taki podejście naucza niewiele poza tym, jak przekonująco może brzmieć błędna odpowiedź.
Text-to-SQL zajmuje swoje miejsce w architekturze jako jeden z przydatnych sposobów wykonywania zadań. Problem polega na tym, że to zbyt ograniczony pojęcie, by opisać cały system. Ten temat prawdopodobnie podzieli zespoły na dwie grupy: osoby, które traktują Text-to-SQL jako odrębny produkt, oraz te, które widzą w nim jedynie cienką warstwę w ramach szerszego procesu analitycznego. Warto zadać pytania: skąd pochodzą największe błędy (ambiwalencja, trudności w wyszukiwaniu danych, przestarzałość informacji lub słabe procedury), czy fundamenty niezbędne agentowi analitycznemu już istnieją, czy też projekt ujawni ukryte problemy z modelem danych, oraz co obecnie zawiera warstwa umiejętności – czy to prompty, instrukcje działania, przykłady SQL czy listy kontrolne dla analityków.
Dodatek: pełny szablon umiejętności
Poniżej znajduje się kompletny szablon umiejętności od Anthropic.
---
name: [warehouse-skill]
version: [x.y.z]
description: "IF the user asks to query [the company]'s data warehouse for any
[list of business domains] question — THEN invoke this skill. DO NOT invoke
for [adjacent engineering tasks] or questions with no data-warehouse component."
---
# [Warehouse] Skill Instructions
## Description
The single source of truth for safe and effective [warehouse] querying.
Referenced by other skills [listed] for query execution guidance.
Act as a Data Analyst, providing strategic insights and data-driven
recommendations but seek guidance along the way.
**Out-of-scope decisions**: [product areas, etc.] → surface data only,
state "decision is [owning team]'s call", do NOT take a position or author
code fixes.
## Executing queries
Priority:
1. **[Managed connection]** (if available): [query tool] / [schema tool]
2. **[CLI fallback]** (if installed): [default project, fallback project]
3. **Neither** — ask the user to authenticate, then stop
---
# Semantic Layer (REQUIRED first step)
The governed semantic layer is the **mandatory default path** for every data
question — same numbers as [the BI tool], joins/grain/filters baked in. Raw SQL
via the reference docs below is the **fallback**, used only after the
semantic-layer path is shown not to cover the ask.
## Required workflow
1. **Load** — [how to load the semantic layer in each runtime, with fallbacks]
2. **Discover** — search measures/dimensions by keyword; **always check
segments** (the named canonical population filters — hand-rolled WHERE
clauses for these are the dominant wrong-answer mode)
3. **Compile + run** — build the spec → compile to SQL → execute
4. **Fallback** — only if discovery finds no relevant metric or compile fails
→ raw SQL via `references/*.md` (PART 3 below)
> **Don't bail early.** Do NOT fall back to raw SQL on these grounds:
> - "[custom date filtering / cohorts]" → [covered by time-dimension specs]
> - "[needs a join]" → [the metric layer already encapsulates its joins]
> - [3–4 more pre-rebutted excuses agents use to skip the semantic layer]
### Date windows & timezone — decide before you query
- **As-of date vs trailing-N days**: [convention for each]
- **"Last week/month"** → the last *complete* calendar week/month, not trailing-7/30
- **Timezone default**: [TZ]; [exception for certain reporting rollups]
- **Freshness lag**: [some] tables settle late — anchor on MAX(date), not "yesterday"
---
# PART 1: MUST KNOW (Read First for Every Request)
## 🚀 Quick Start Workflow
1. **Check for red flags first**: [restricted/PII requests, gated domains,
high-stakes asks that need extra validation]
2. **Out of scope — escalate, don't guess**: [access requests, pipeline
troubleshooting, stale dashboards, root-cause assertions, product/pricing
recommendations] → redirect to [the owning team], don't answer
3. **Clarify the request**: time period, segment, the business decision it informs
4. **Check for existing dashboards**: [per-domain dashboard catalogs]
5. **Identify the data source**: [navigation map below; prefer governed/aggregated tables]
6. **Execute the analysis**: [required filters + adversarial review]
7. **Deliver insights**: show methodology, differentiate observations from interpretations
## 🏢 Business Context
### Entity Disambiguation (MUST CLARIFY)
- **"[Term A]" can mean**: [entity 1] or [entity 2] — always clarify which
- **"[Term B]" can mean**: [entity 1] → [entity 2] → [entity 3] (one-to-many chain)
- **"Users"**: [which identifier gives accurate counts, and which ones inflate them]
### Business Terminology
- [Current product names vs deprecated aliases that still appear as frozen
values in the data layer — write with the new names, filter with the old]
- [Key internal acronyms]
- **[Headline metric] calculations**: [monthly / default window / leading indicator]
- **Unfamiliar terms — search [internal docs], don't guess**
### Data Integrity Requirements ⚠️
- **NEVER**: make up data/columns; make speculative assertions beyond what data shows
- **ALWAYS**: use safe division; differentiate observations ("data shows X")
from interpretations ("this suggests Y"); flag limitations
---
# PART 2: HOW TO DO (Follow During Execution)
## 🔧 Technical Execution Guide
- [Managed-connection tools and CLI invocation details]
- **PII protection**: for restricted data, return the SQL for the user to run
themselves — do not return results
## 📊 Analysis Best Practices Guide
1. Clarify the ask before querying
2. Show your work (filters, inclusions/exclusions, freshness)
3. Clarify denominators
4. Consider sample bias
5. Connect to business impact
6. **Adversarial SQL review (MANDATORY)** — spawn the [sql-reviewer] sub-agent
for every query before the final answer; blocking findings must be fixed
and re-reviewed; do not self-certify
7. **Report with provenance** — every answer ends with a footer:
> **Source:** [semantic layer | governed table | raw exploration] ·
> **Confidence:** [tier] · **Reviewed:** [reviewer ✓, round N] ·
> **Freshness:** [max date in the data] · **Owner:** [owning team]
---
# PART 3: DATA REFERENCES & RESOURCES
## 📚 Knowledge Base Navigation
### [Domain A] → `references/[domain_a].md`
- **Use for**: [kinds of questions]
- **Key tables**: [...]
- **Dashboards**: `references/[domain_a]_dashboards.json`
### [Domain B] → `references/[domain_b].md`
- **Use for**: [...]
[... one entry per business domain — a few dozen in total ...]
## ⚠️ Troubleshooting Guide
### When Information Is Missing
- [missing tables / access denied / outdated docs / unknown enum values → what to do]
### Field Naming Gotchas
- Use `[field_x_v2]` NOT `[field_x]`
- [Two similarly-named tables report the same metric at different grains — which to use]
- [Which of two plausible sources is canonical for the headline metric]
- [… a dozen more hard-won one-liners …]
Powiązane materiały
- DS-STAR wyjaśniony: agent nauk o danych Google i powody sukcesu jego rozwiązania — Przegląd agenta nauk o danych DS-STAR firmy Google: jego siedem modułów, pętla raportowania DS-STAR+, opublikowane instrukcje, wyniki testów ablacji oraz istniejące ograniczenia.
- Czterowarstwowy projekt pamięci dla agentów AI z informacjami o pochodzeniu danych — Podział pamięci krótkoterminowej i długoterminowej, cztery warstwy (buforowa, epizodyczna, semantyczna, proceduralna), opcje przechowywania, zapisy asynchroniczne oraz metody ochrony przed zatruwaniem pamięci.