Development z AI: Python, Refactoring i Wzorce Architektury

Ten artykuł zbiera najlepsze praktyki development’u z pomocą AI - od bibliotek Python, przez TDD i refactoring, po wzorce architektoniczne agentów i organizację projektu.

10 Bibliotek Python dla Generative AI (2026)

Kluczowe biblioteki które musisz opanować jako AI engineer:

Orchestracja i Frameworki

LangChain - najpopularniejszy framework do budowania LLM apps

Chains, agents, tools
Duży ekosystem integracji
Uwaga: może być overkill dla prostych cases

LangGraph - dla złożonej logiki jako grafów

Stateful agents
Cykle i pętle w workflow
Lepszy niż linearne LangChain chains dla agentów

LlamaIndex - specjalizacja w RAG i data connectors

Indeksowanie dokumentów
Query engines
Lepsza alternatywa niż LangChain dla pure RAG

LLM Providers SDK

Anthropic SDK - oficjalny Python SDK dla Claude

pip install anthropic

OpenAI SDK - dla GPT models

pip install openai

Hugging Face Transformers - dla lokalnych modeli

pip install transformers

Vector Databases (Python Client)

Weaviate - najlepszy dla hybrid search (vector + keyword)

Pinecone - managed, production-ready

Chroma - lokalne wdrożenia, idealny do development

Milvus - high performance dla dużych datasetów

Evaluation i Testing

Ragas - end-to-end RAG evaluation DeepEval - component testing dla LLM apps

Narzędzia Produkcyjne

Tenacity - retries i backoff (critical dla API calls) Instructor - structured outputs z LLM Pydantic - walidacja danych, type hints

“Add a few boring but crucial ones: tenacity for retries and backoff, structured logging and tracing, and something for evals. In gen AI projects, the fastest way to improve is a repeatable benchmark suite plus regression tests on real prompts.”

Refactoring z Claude: Doświadczenie Uncle Boba

Robert “Uncle Bob” Martin - legenda software craftsmanship - ujawnił swoje doświadczenia z Claude w roli “merciless refactorer”:

Kluczowe odkrycia:

1. Refactoring jako konieczność, nie opcja

“When I don’t press on refactoring I start getting API errors because the tasks cannot fit in the context window. Then I refactor and all is well. So nowadays I refactor like crazy to keep the tasks within the ken of Claude.”

Wniosek praktyczny: Refactoring to nie estetyka - to engineering konieczność gdy współpracujesz z AI. Modularne, małe funkcje = mniejsze zadania = lepsze wyniki.

2. TDD jako klucz do bezpiecznego refactoringu Narzędzia Uncle Boba:

Unit tests z intensywnym TDD (3 laws of TDD)
Gherkin acceptance tests
Mutation testing → massive over-specification testów

“The tests are so overloaded that Claude can’t break free.”

Semantic stability mimo “ripping the guts out of the code and rearranging at my whim”.

3. Mutation Testing Mutation testing prowadzi do masywnej over-specification w testach. Efekt: Claude nie może “uciec” z wymagań - każda zmiana zachowania jest wychwytywana przez testy.

4. Odkrywanie dead code i duplicacji Claude sam odkrywa:

Zduplikowany kod podczas refactoringu
Dead code
Słabe struktury kodu

“When you force it to focus on coverage and cyclomatic complexity it discovers all sorts of things.”

5. Metryka: CRAP score Uncle Bob używa crap4clj - narzędzia do mierzenia “CRAP score” (Change Risk Anti-Patterns) dla modułów z wysokim cyclomatic complexity.

Praktyczne wnioski

Działanie	Efekt
TDD + mutation testing	Semantyczna stabilność podczas refactoringu
Małe, modularne funkcje	Mniejsze zadania mieszczą się w context window
Regularne refaktorowanie	Lepsze wyniki Claude (mniejszy kontext = lepsza jakość)
Code review po AI	Szukaj duplikacji i dead code

“Test Driven Development stocks are going up.” “Massive, overloaded testing is the only guarantee of semantic stability.”

Wzorce Architektoniczne AI: Awesome Agentic Patterns

Katalog sprawdzonych wzorców dla systemów agentic AI:

Kluczowe wzorce (z github.com/nibzard/awesome-agentic-patterns)

1. Explicit State + Checkpoints Zawsze przechowuj explicit stan agenta. Checkpoints pozwalają na resume po błędzie.

2. Escalation Path Gdy confidence jest niski → eskaluj do ludzkiego nadzoru. Większość awarii agentów wynika z brakujących guardrails, nie jakości modelu.

3. Single Responsibility Agent Każdy agent robi jedną rzecz. Unikaj “do everything” agentów.

4. Verification Before Done Nigdy nie oznaczaj zadania jako complete bez dowodu że działa. “Would a staff engineer approve this?”

5. Memory Patterns

Working memory (context window)
Episodic memory (task logs)
Semantic memory (knowledge base)
Procedural memory (skills)

6. Tool Use Hierarchy Nie dawaj agentowi wszystkich narzędzi naraz. Hierarchia narzędzi bazująca na potrzebie.

7. Human-in-the-Loop Gates Dla nieodwracalnych akcji (delete, deploy, email to client) - wymaga ludzkiego zatwierdzenia.

Pro tip: Poproś coding agenta żeby przekonwertował codebase w diagram Excalidraw przez MCP server. Świetny sposób żeby zwizualizować i zrozumieć architekturę.

Docs Structure: Organizacja Projektu

Optymalna struktura dokumentacji dla projektów z AI:

Poziomy dokumentacji

CLAUDE.md - Root level

Standardy projektu
Konwencje kodowania
Instrukcje dla agenta
Non-negotiables

docs/ - Dokumentacja architekturalna

Architecture Decision Records (ADR)
System design
API documentation
Deployment guides

tasks/ - Task management

todo.md - aktualny plan i postęp
lessons.md - czego agent się nauczył

src/ - Logika aplikacji

Modularne, małe pliki
Każdy plik = jedno odpowiedzialność

tools/ - Skrypty i utilities

Helper scripts
Build tools
CI/CD configs

skills/ - Reusable workflows

Per-task skills
Organizacyjne wzorce

hooks/ - Automatyczna walidacja

Pre-tool validation
Post-tool cleanup

Zasady organizacji

Separation of Concerns - AI layer nie może “bleeding into” application layer
Modularity - małe, niezależne komponenty
Explicitness - AI potrzebuje jasnych granic
Traceability - kto co kiedy zmienił i dlaczego

Superpowers: Framework Full Engineering Workflow

Superpowers to open-source agentic skills framework dający Claude Code kompletny software development brain.

Podstawowe zasady:

Spec before code - brainstorming przed implementation
Bite-sized tasks - rozbij implementację na małe zadania
Subagent-driven - parallel execution
TDD enforcement - RED-GREEN-REFACTOR
Mandatory workflows - nie pozwól agentowi pominąć planowania

Dlaczego AI coding agents zawodzą:

Piszą kod zanim rozumieją problem
Ogłaszają sukces zanim uruchomią testy
Halucynują plany i brnąt dalej

Superpowers rozwiązuje to mandatory workflows:

You say: "Build me a Stripe payment integration"

Superpowers:
1. Asks clarifying questions → locks in spec
2. Breaks work into 2-5 min tasks with exact file paths
3. Launches subagents per task with two-stage code review
4. Enforces failing test → passing → committed

Technical setup:

/plugin marketplace add superpowers

Claude Code plugin (one-line install)
Also supports Codex and OpenCode
15+ composable skills (TDD, debugging, git worktrees, parallel agents)
MIT license

Context Engineering: Fundament Dobrego AI Development

“Prompt Engineering is dead. Context Engineering is king.”

Context to największy problem z coding agentami. Nawet przeciętny model może dać świetne wyniki z odpowiednim kontekstem.

Techniki context engineering:

1. CLAUDE.md jako projekt memory Nie repeating instrukcji w każdym prompcie - centralny punkt prawdy.

2. Semantic indexing (nie keyword) Knowledge graph rozumie strukturę kodu i powiązania między plikami. Augment Code Context Engine: 2x szybsze odpowiedzi na 30K+ linii kodu.

3. Knowledge graph

CLAUDE.md points at → notes/ directory per task
→ Updated after every PR
→ Agent knows project history

4. Doc:Code ratio Optymalny stosunek dokumentacji do kodu: 3.6:1. Gdy AI ma structured specs, architecture docs i decision logs - jakość dramatycznie wzrasta.

Wzorzec PRD (Product Requirements Document) w Erze AI

PRD nie jest martwy - ale ewoluował.

Co PRD zawiera (i czego prototype nie):

Hipoteza co budujesz i dlaczego
Jak to wpisuje się w strategię
A/B test plan lub rollout strategy
Definicja sukcesu (metryki)
Non-goals i potencjalne side-effects

Jak pisać PRD w 2026:

Nie pisz długich eseji - AI generuje bloat
Bullet points > pełne zdania
Decyzje > opcje (wybierz jedno, uzasadnij)
“What would break this?” - pytaj o failure modes
Alignment artifact - to co team dyskutuje, nie model do waterfall

Claude workflow:

Meeting transcript → PRD → Jira tickets → Slack summary → Dashboard

Praktyczne Zasady dla AI Development

Do (Co Robić)

Zawsze spec przed code - wymagania + architektura przed linią kodu
Modular, small files - Claude działa lepiej na małych, skupionych plikach
TDD jako safety net - daje confidence do agresywnego refactoringu
Regular refactoring - utrzymuj tasks w rozmiarze context window
Commit atomically - każde zadanie = jeden commit
Document decisions - ADR w docs/

Don’t (Czego Unikać)

Nie twórz monolitycznych plików - >300 linii to sygnał do rozbicia
Nie pomijaj testów - “just this once” prowadzi do kumulacji długu technicznego
Nie dawaj agentowi nieskończonego scope’u - jasne granice zadania
Nie ignoruj context rot - monitoruj jakość outputów z czasem
Nie ufaj blind outputs - zawsze code review, nawet AI-generated

Podsumowanie

Współpraca z AI w development to nie zastąpienie inżynierów - to amplifikacja możliwości. Kluczowe wzorce:

Structure first - CLAUDE.md, modularne pliki, jasna dokumentacja
TDD jako fundament - bezpieczny refactoring, semantyczna stabilność
Spec before code - Superpowers, GSD, BMAD patterns
Context engineering - knowledge graph > keyword search
Atomic commits - agent commituje po każdym zadaniu
Continuous evaluation - eval suite dla AI outputs