Agent skill · software engineering · jeremylongshore
langchain-reference-architecture
A reference layered architecture for production LangChain 1.0 / LangGraph\
Why this skill is useful
Provides a complete reference architecture with specific patterns and practices for building LangChain services, including executable directory structure and dependency management.
What it needs
Requires import-linter, langchain-core, langgraph, pydantic, python installed locally. About 9k tokens when loaded. Last updated 2026-08-07. 2,604 stars on the source repository.
What this skill does
LangChain Reference Architecture (Python) Overview Eight months into a LangChain service, a code review surfaces the mess. Twelve chain definitions live inlined inside FastAPI route handlers. Three retrievers are constructed at module-global scope, one bound to tenantid="acme" because that was the first tenant in the pilot — that retriever now returns Acme's documents to every other tenant, a P33 leak that has been live in production for six weeks. maxretries=6 is hardcoded at four separate call sites. A RunnableWithMessageHistory backed by the default InMemoryChatMessageHistory loses every conversation on pod restart (P22) — which is most days, because Cloud Run scales to zero. Config is read from os.environ in three modules with three different fallback strategies. There is no place to put a new provider without touching seven files, and nobody remembers why the retriever is built at import time. The fix is not "rename a variable." The fix is an architecture that made every one of those mistakes hard to write. This skill is the target layered architecture: app/ — FastAPI routes. Thin. Parses HTTP, calls into services, serializes response. No chain logic, no vendor clients, no env vars. services/ — chain and graph definitions. Take dependencies through constructor args, not module-level imports. adapters/ — vendor clients, LLM factory, retriever factory, tool factory. This is where langchain-anthropic is imported. Nowhere else. config/ — one Pydantic Settings class. SecretStr for keys, Literal["dev","staging","prod"] for env names, .env file loader. domain/ — Pydantic models, typed LangGraph state, enums. No I/O. Five layers, five imports deep at most. Dependency direction is strictly downward. app imports services; services imports adapters; adapters imports config and domain. Never the reverse. Import-linter enforces this in CI. …
How to use it
Reference it in AdaL, Claude Code, Cursor or any coding agent — nothing to install:
@skills jeremylongshore/langchain-reference-architecture