ai-era-architecture-principles

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

AI Era Architecture Principles

AI时代架构原则

Extracted: 2026-02-09 Context: When deciding whether to use large frameworks (LangChain, LiteLLM, etc.) vs custom implementation in the Claude Code era

**提取时间：**2026-02-09 **适用场景：**在Claude Code时代，决策是否使用大型框架（LangChain、LiteLLM等）还是进行自定义实现的场景

Problem

问题背景

Traditional software development wisdom says "Don't Reinvent the Wheel" — use existing libraries and frameworks to save development time. But in the AI-driven development era with Claude Code, is this still the best approach?

Key Questions:

Should I use LangChain for LLM applications?
Should I use a large framework with 50+ dependencies?
When is custom implementation better than a comprehensive library?

传统软件开发的智慧是“不要重复造轮子”——使用现有库和框架来节省开发时间。但在Claude Code驱动的AI开发时代，这是否仍是最佳方案？

核心问题：

我应该为LLM应用使用LangChain吗？
我应该使用包含50+个依赖的大型框架吗？
什么时候自定义实现比综合性库更好？

Solution: The Three Principles

解决方案：三大原则

1. Micro-Dependencies Principle

1. 微依赖原则

Avoid large frameworks when Claude Code can implement needed features in hours.

Traditional Development:
  Custom implementation: weeks → months ⏰
  Use existing framework: days → weeks ✅

Claude Code Era:
  Custom implementation: hours → 1 day ✅
  Use existing framework: still brings 50+ dependencies ❌

Example (pdf2anki project):

❌ With LangChain: 50+ dependencies, black-box abstractions, breaking changes
✅ Custom: 6 dependencies (anthropic, pymupdf, pydantic, pyyaml, typer, rich)
✅ Result: 3,348 lines, full control, 96% test coverage, transparent

Benefits:

Minimal dependencies → Easier maintenance
No black-box abstractions → Full transparency
No framework lock-in → Complete flexibility
Faster startup/install → Better user experience

当Claude Code能在数小时内实现所需功能时，避免使用大型框架。

传统开发模式：
  自定义实现：数周→数月 ⏰
  使用现有框架：数天→数周 ✅

Claude Code时代：
  自定义实现：数小时→1天 ✅
  使用现有框架：仍会引入50+个依赖 ❌

示例（pdf2anki项目）：

❌ **使用LangChain：**50+个依赖、黑盒抽象、易出现破坏性变更
✅ **自定义实现：**仅6个依赖（anthropic、pymupdf、pydantic、pyyaml、typer、rich）
✅ **结果：**3348行代码、完全可控、96%测试覆盖率、逻辑透明

优势：

最小化依赖→更易维护
无黑盒抽象→完全透明
无框架锁定→灵活性拉满
启动/安装更快→更好的用户体验

2. Perfect Fit Principle

2. 完美适配原则

Generic abstractions → Domain-specific design

Large frameworks provide generic solutions that work for many use cases. But your project has specific requirements. With Claude Code, you can implement exactly what you need.

Example (pdf2anki project):

python

undefined

从通用抽象转向领域特定设计

大型框架提供适用于多种场景的通用解决方案，但你的项目有特定需求。借助Claude Code，你可以实现完全匹配需求的功能。

示例（pdf2anki项目）：

python

undefined

Project-specific requirements:

项目特定需求：

@dataclass(frozen=True) # ← Immutability requirement class Section: # Structure-aware chunking for long documents heading_stack: tuple[str, ...] # Per-section model routing (Haiku vs Sonnet) char_count: int

@dataclass(frozen=True) # ← 不可变性要求 class Section: # 长文档的结构感知分块 heading_stack: tuple[str, ...] # 按章节路由模型（Haiku vs Sonnet） char_count: int

Batch API with 50% discount (Claude-specific)

批量API享50%折扣（Claude专属）

client.messages.batches.create(requests=[...])

Prompt caching control (Claude-specific)

提示词缓存控制（Claude专属）

system=[{ "type": "text", "text": SYSTEM_PROMPT, "cache_control": {"type": "ephemeral"} # ← Direct control }]


These features are perfectly tailored to the project's needs. A generic framework would either:
- Not support these features, or
- Support them through complex configuration/plugins

**Benefits:**
- Code matches domain model exactly
- No unused features → Simpler codebase
- Direct control over critical features

---

system=[{ "type": "text", "text": SYSTEM_PROMPT, "cache_control": {"type": "ephemeral"} # ← 直接控制 }]


这些功能完全贴合项目需求。而通用框架要么：
- 不支持这些功能，要么
- 通过复杂配置/插件实现支持

**优势：**
- 代码与领域模型完全匹配
- 无冗余功能→代码库更简洁
- 对关键功能拥有直接控制权

---

3. Full Control Principle

3. 完全可控原则

Complete control over API calls, cost tracking, error handling

With direct SDK usage, you understand every line of code. With frameworks, behavior is hidden behind abstractions.

Example:

python

undefined

对API调用、成本追踪、错误处理拥有完全控制权

直接使用SDK时，你能理解每一行代码的逻辑。而使用框架时，行为被隐藏在抽象层之后。

示例：

python

undefined

✅ Direct SDK: Crystal clear what happens

✅ 直接使用SDK：逻辑清晰透明

client = anthropic.Anthropic() response = client.messages.create( model=model, max_tokens=max_tokens, system=[...], # Explicit prompt caching messages=[...] ) cost = (response.usage.input_tokens / 1_000_000) * PRICE_PER_1M

client = anthropic.Anthropic() response = client.messages.create( model=model, max_tokens=max_tokens, system=[...], # 显式提示词缓存 messages=[...] ) cost = (response.usage.input_tokens / 1_000_000) * PRICE_PER_1M

❌ Framework: What's happening internally?

❌ 使用框架：内部逻辑不透明

llm = ChatAnthropic(model=model) chain = prompt | llm | parser result = chain.invoke({"text": text}) # Caching enabled? Cost?


**Benefits:**
- Debugging is easy → No abstraction layers to dig through
- Testing is simple → Mock at SDK level
- Performance optimization → Profile exact bottlenecks
- Cost control → Track every token

---

llm = ChatAnthropic(model=model) chain = prompt | llm | parser result = chain.invoke({"text": text}) # 是否启用缓存？成本多少？


**优势：**
- 调试更简单→无需深挖抽象层
- 测试更便捷→在SDK层进行Mock
- 性能优化精准→定位确切瓶颈
- 成本可控→追踪每一个token的消耗

---

The New Mantra

新准则

Traditional Era

传统时代

"Don't Reinvent the Wheel"

“不要重复造轮子”

AI Era (with Claude Code)

AI时代（Claude Code）

"Don't Import the Warehouse for a Single Wheel"

Why?

Claude Code can build the exact wheel you need in hours
Importing the warehouse (large framework) brings:
- 50+ dependencies you don't need
- Features you'll never use
- Complexity you don't want
- Breaking changes you must handle

“不要为了一个轮子而引进整个仓库”

原因：

Claude Code可以在数小时内构建你所需的“轮子”
引进“仓库”（大型框架）会带来：
- 50+个你不需要的依赖
- 永远不会用到的功能
- 不必要的复杂度
- 必须处理的破坏性变更

When to Use Large Frameworks

何时使用大型框架

Large frameworks ARE valuable when:

You need 80%+ of the framework's features
- Example: Django for full-stack web apps (ORM, auth, admin, forms, templates)
The framework provides critical infrastructure you can't easily replicate
- Example: React for complex UI state management
You're prototyping and speed > control
- Example: Using LangChain to quickly test different LLM providers
The framework has strong network effects
- Example: TensorFlow/PyTorch for ML (ecosystem, community, tools)

在以下场景中，大型框架仍具有价值：

你需要该框架80%以上的功能
- 示例：使用Django开发全栈Web应用（ORM、认证、后台管理、表单、模板）
框架提供了你难以自行复制的关键基础设施
- 示例：使用React进行复杂UI状态管理
你正在原型开发，速度优先级高于控制权
- 示例：使用LangChain快速测试不同LLM提供商
框架拥有强大的网络效应
- 示例：使用TensorFlow/PyTorch进行机器学习（生态系统、社区、工具完善）

When to Avoid Large Frameworks

何时避免使用大型框架

Avoid large frameworks when:

You need < 20% of the framework's features
- Example: Using LangChain just for API calls to Claude/OpenAI
Your requirements are highly specific
- Example: Custom cost tracking, specific batching logic, domain-specific optimizations
You value simplicity and control
- Example: CLI tools, libraries, utilities
The framework is rapidly changing
- Example: Early-stage AI frameworks with frequent breaking changes

在以下场景中，应避免使用大型框架：

你仅需要该框架20%以下的功能
- 示例：仅使用LangChain调用Claude/OpenAI的API
你的需求具有高度特异性
- 示例：自定义成本追踪、特定批量逻辑、领域专属优化
你重视简洁性与控制权
- 示例：CLI工具、类库、实用程序
框架处于快速迭代变化中
- 示例：处于早期阶段、频繁出现破坏性变更的AI框架

Decision Framework

决策框架

┌─────────────────────────────────────────────┐
│ Do I need > 50% of the framework features?  │
└─────────────┬───────────────────────────────┘
              │
         No ──┴── Yes
         │        │
         │        └─→ Use Framework
         │
         ▼
┌─────────────────────────────────────────────┐
│ Are my requirements highly specific?        │
└─────────────┬───────────────────────────────┘
              │
         No ──┴── Yes
         │        │
         │        └─→ Custom Implementation
         │
         ▼
┌─────────────────────────────────────────────┐
│ Can Claude Code implement it in < 1 day?    │
└─────────────┬───────────────────────────────┘
              │
         No ──┴── Yes
         │        │
         │        └─→ Custom Implementation
         │
         └─→ Consider Framework

┌─────────────────────────────────────────────┐
│ 我是否需要该框架50%以上的功能？              │
└─────────────┬───────────────────────────────┘
              │
         否 ──┴── 是
         │        │
         │        └─→ 采用框架
         │
         ▼
┌─────────────────────────────────────────────┐
│ 我的需求是否具有高度特异性？                  │
└─────────────┬───────────────────────────────┘
              │
         否 ──┴── 是
         │        │
         │        └─→ 自定义实现
         │
         ▼
┌─────────────────────────────────────────────┐
│ Claude Code能否在1天内实现所需功能？         │
└─────────────┬───────────────────────────────┘
              │
         否 ──┴── 是
         │        │
         │        └─→ 自定义实现
         │
         └─→ 考虑采用框架

Real-World Example: pdf2anki

实际案例：pdf2anki

Decision: Add OpenAI API support alongside Claude API

Option 1: Use LangChain

Dependencies: +10 packages (langchain, langchain-core, langchain-anthropic, langchain-openai, etc.)
Code: ~200 lines (shorter)
Control: Limited (cost tracking, batch API, caching = opaque)
Maintenance: Must track LangChain updates

Option 2: Custom Provider Abstraction

Dependencies: +1 package (openai SDK)
Code: ~500 lines (longer, but all visible)
Control: Complete (cost tracking, batch API, caching = explicit)
Maintenance: Only SDK updates (Anthropic, OpenAI)

Chosen: Option 2 with conditional dependencies (even better!)

toml

[project.optional-dependencies]
claude = ["anthropic>=0.40.0"]
openai = ["openai>=1.0.0"]
all = ["anthropic>=0.40.0", "openai>=1.0.0"]

Users install only what they need:

bash

pip install pdf2anki[claude]   # Only Anthropic SDK
pip install pdf2anki[openai]   # Only OpenAI SDK
pip install pdf2anki[all]      # Both (for comparison)

Result:

Micro-Dependencies ✅ (users choose)
Perfect Fit ✅ (domain-specific features preserved)
Full Control ✅ (transparent cost tracking, batch API)

**决策场景：**在Claude API之外添加OpenAI API支持

方案1：使用LangChain

依赖：新增10个包（langchain、langchain-core、langchain-anthropic、langchain-openai等）
代码量：约200行（更短）
控制权：有限（成本追踪、批量API、缓存逻辑不透明）
维护：必须跟进LangChain的更新

方案2：自定义提供商抽象层

依赖：新增1个包（openai SDK）
代码量：约500行（更长，但逻辑完全可见）
控制权：完全可控（成本追踪、批量API、缓存逻辑显式可查）
维护：仅需跟进SDK更新（Anthropic、OpenAI）

最终选择：方案2 + 可选依赖（更优！）

toml

[project.optional-dependencies]
claude = ["anthropic>=0.40.0"]
openai = ["openai>=1.0.0"]
all = ["anthropic>=0.40.0", "openai>=1.0.0"]

用户可按需安装：

bash

pip install pdf2anki[claude]   # 仅安装Anthropic SDK
pip install pdf2anki[openai]   # 仅安装OpenAI SDK
pip install pdf2anki[all]      # 两者都安装（用于对比）

结果：

微依赖原则 ✅（用户自主选择）
完美适配原则 ✅（领域特定功能得以保留）
完全可控原则 ✅（透明的成本追踪、批量API）

When to Use This Skill

何时使用该方法

Trigger: When you or the user are considering adding a large framework (especially for LLM applications).

Questions to Ask:

What percentage of the framework's features will we actually use?
Can Claude Code implement the needed features in < 1 day?
Are there project-specific requirements that need fine-grained control?
How important is dependency minimization for this project?

Remember: In the AI era, the cost of custom implementation has dropped dramatically. Factor this into your architecture decisions.

**触发场景：**当你或用户考虑为项目引入大型框架（尤其是LLM应用相关框架）时。

需询问的问题：

我们实际会用到该框架多少比例的功能？
Claude Code能否在1天内实现所需功能？
项目是否有需要精细控制的特定需求？
依赖最小化对该项目有多重要？

**记住：**在AI时代，自定义实现的成本已大幅降低。请将这一点纳入你的架构决策中。

ai-era-architecture-principles

Original

Translation

AI Era Architecture Principles

AI时代架构原则

Problem

问题背景

Solution: The Three Principles

解决方案：三大原则

1. Micro-Dependencies Principle

1. 微依赖原则

2. Perfect Fit Principle

2. 完美适配原则

Project-specific requirements:

项目特定需求：

Batch API with 50% discount (Claude-specific)

批量API享50%折扣（Claude专属）

Prompt caching control (Claude-specific)

提示词缓存控制（Claude专属）

3. Full Control Principle

3. 完全可控原则

✅ Direct SDK: Crystal clear what happens

✅ 直接使用SDK：逻辑清晰透明

❌ Framework: What's happening internally?

❌ 使用框架：内部逻辑不透明

The New Mantra

新准则

Traditional Era

传统时代

AI Era (with Claude Code)

AI时代（Claude Code）

When to Use Large Frameworks

何时使用大型框架

When to Avoid Large Frameworks

何时避免使用大型框架

Decision Framework

决策框架

Real-World Example: pdf2anki

实际案例：pdf2anki

When to Use This Skill

何时使用该方法

Related Patterns

相关模式