Karpathy 四大原则：LLM 编码陷阱与 Claude Code 最佳实践

#!/usr/bin/env python3
"""
Think Before Coding - 显式推理框架
在 LLM 编码前强制进行结构化思考
"""
from dataclasses import dataclass, field
from enum import Enum
from typing import List, Optional

class ConfidenceLevel(Enum):
    HIGH = "high"       # 明确理解
    MEDIUM = "medium"   # 部分理解，有合理假设
    LOW = "low"         # 存在重大不确定性

@dataclass
class Assumption:
    """编码前必须声明的假设"""
    description: str
    confidence: ConfidenceLevel
    impact_if_wrong: str  # 如果假设错误的后果
    alternative: Optional[str] = None  # 替代解释

@dataclass
class ClarifyingQuestion:
    """需要向用户澄清的问题"""
    question: str
    why_it_matters: str  # 为什么这个问题重要
    blocking: bool = False  # 是否阻塞后续工作

@dataclass
class PreCodingAnalysis:
    """编码前的完整分析"""
    task_understanding: str
    assumptions: List[Assumption] = field(default_factory=list)
    questions: List[ClarifyingQuestion] = field(default_factory=list)
    proposed_approaches: List[str] = field(default_factory=list)
    tradeoffs: List[str] = field(default_factory=list)
    recommended_approach: str = ""

    def has_low_confidence(self) -> bool:
        """是否存在低置信度假设"""
        return any(a.confidence == ConfidenceLevel.LOW for a in self.assumptions)

    def has_blocking_questions(self) -> bool:
        """是否有阻塞性问题"""
        return any(q.blocking for q in self.questions)

    def should_ask_before_coding(self) -> bool:
        """是否应该在编码前提问"""
        return self.has_low_confidence() or self.has_blocking_questions()

    def generate_report(self) -> str:
        """生成分析报告"""
        lines = [f"📋 任务理解：{self.task_understanding}", ""]
        if self.assumptions:
            lines.append("🔍 假设清单：")
            for a in self.assumptions:
                lines.append(f"  - {a.description} (置信度: {a.confidence.value})")
                if a.alternative:
                    lines.append(f"    替代方案: {a.alternative}")
            lines.append("")
        if self.questions:
            lines.append("❓ 澄清问题：")
            for q in self.questions:
                tag = "🚫 阻塞" if q.blocking else "⚠️ 非阻塞"
                lines.append(f"  {tag} {q.question} ({q.why_it_matters})")
            lines.append("")
        if self.proposed_approaches:
            lines.append("💡 可选方案：")
            for i, approach in enumerate(self.proposed_approaches, 1):
                lines.append(f"  {i}. {approach}")
            lines.append("")
        if self.should_ask_before_coding():
            lines.append("⛔ 建议：在编码前先回答上述问题")
        return "\n".join(lines)

# 使用示例：LLM 在编码前必须填充这个结构
def analyze_before_coding(task_description: str) -> PreCodingAnalysis:
    analysis = PreCodingAnalysis(
        task_understanding="理解用户的具体需求",
        assumptions=[
            Assumption(
                description="用户需要一个 REST API 而非 GraphQL",
                confidence=ConfidenceLevel.MEDIUM,
                impact_if_wrong="可能需要完全重写接口层",
                alternative="GraphQL 可能更适合复杂查询场景"
            ),
            Assumption(
                description="使用 PostgreSQL 作为数据库",
                confidence=ConfidenceLevel.HIGH,
                impact_if_wrong="迁移成本较高",
            ),
        ],
        questions=[
            ClarifyingQuestion(
                question="认证方式是 JWT 还是 OAuth2？",
                why_it_matters="影响安全架构设计",
                blocking=True,
            ),
            ClarifyingQuestion(
                question="是否需要分页？数据量预估多大？",
                why_it_matters="影响查询优化策略",
                blocking=False,
            ),
        ],
        proposed_approaches=[
            "FastAPI + SQLAlchemy + Pydantic v2",
            "Django REST Framework（更重的框架但更成熟）",
        ],
        tradeoffs=["方案 1 更轻量但生态较小", "方案 2 更重但文档丰富"],
        recommended_approach="推荐方案 1，除非有特殊需求",
    )
    return analysis

if __name__ == "__main__":
    analysis = analyze_before_coding("构建用户管理 API")
    print(analysis.generate_report())
    if analysis.should_ask_before_coding():
        print("\n⛔ 请先回答澄清问题再继续编码！")

#!/usr/bin/env python3
"""
Simplicity First - 代码复杂度检测与简化建议
"""
import ast
import sys
from dataclasses import dataclass
from typing import List

@dataclass
class ComplexityIssue:
    """复杂度问题"""
    type: str
    location: str
    description: str
    suggestion: str
    severity: str  # "high" | "medium" | "low"

class SimplicityChecker(ast.NodeVisitor):
    """AST 级别的代码简洁性检查器"""

    def __init__(self):
        self.issues: List[ComplexityIssue] = []
        self._current_class = ""
        self._current_func = ""

    def visit_ClassDef(self, node: ast.ClassDef):
        self._current_class = node.name
        # 检查类是否过于臃肿
        methods = [n for n in node.body if isinstance(n, (ast.FunctionDef, ast.AsyncFunctionDef))]
        if len(methods) > 15:
            self.issues.append(ComplexityIssue(
                type="bloated_class",
                location=f"class {node.name}",
                description=f"类包含 {len(methods)} 个方法，可能违反单一职责原则",
                suggestion="考虑拆分为多个职责单一的小类",
                severity="high",
            ))
        self.generic_visit(node)
        self._current_class = ""

    def visit_FunctionDef(self, node: ast.FunctionDef):
        self._current_func = node.name
        # 检查函数行数
        end_line = node.end_lineno or node.lineno
        line_count = end_line - node.lineno
        if line_count > 50:
            self.issues.append(ComplexityIssue(
                type="long_function",
                location=f"def {node.name}()",
                description=f"函数 {line_count} 行，超过 50 行建议值",
                suggestion="拆分为多个小函数，每个函数只做一件事",
                severity="medium",
            ))
        # 检查嵌套层级
        max_depth = self._get_max_depth(node)
        if max_depth > 4:
            self.issues.append(ComplexityIssue(
                type="deep_nesting",
                location=f"def {node.name}()",
                description=f"嵌套深度 {max_depth} 层，超过 4 层建议值",
                suggestion="使用提前返回（early return）减少嵌套",
                severity="high",
            ))
        # 检查不必要的抽象
        if len(node.decorator_list) > 3:
            self.issues.append(ComplexityIssue(
                type="over_decorated",
                location=f"def {node.name}()",
                description=f"函数有 {len(node.decorator_list)} 个装饰器",
                suggestion="过多的装饰器可能表示过度抽象",
                severity="low",
            ))
        self.generic_visit(node)

    def _get_max_depth(self, node: ast.AST, current_depth: int = 0) -> int:
        max_d = current_depth
        for child in ast.iter_child_nodes(node):
            if isinstance(child, (ast.If, ast.For, ast.While, ast.With, ast.Try)):
                child_depth = self._get_max_depth(child, current_depth + 1)
                max_d = max(max_d, child_depth)
            else:
                child_depth = self._get_max_depth(child, current_depth)
                max_d = max(max_d, child_depth)
        return max_d

    def get_report(self) -> str:
        if not self.issues:
            return "✅ 代码简洁性检查通过！没有发现过度复杂的问题。"
        lines = ["📊 代码简洁性检查报告：", ""]
        for issue in self.issues:
            emoji = {"high": "🔴", "medium": "🟡", "low": "🟢"}[issue.severity]
            lines.append(f"{emoji} [{issue.type.upper()}] {issue.location}")
            lines.append(f"   问题: {issue.description}")
            lines.append(f"   建议: {issue.suggestion}")
            lines.append("")
        return "\n".join(lines)

def check_file_simplicity(filepath: str) -> str:
    with open(filepath, 'r', encoding='utf-8') as f:
        source = f.read()
    tree = ast.parse(source)
    checker = SimplicityChecker()
    checker.visit(tree)
    return checker.get_report()

if __name__ == "__main__":
    # 检查当前脚本自身
    print(check_file_simplicity(__file__))

#!/usr/bin/env python3
"""
Karpathy Four Principles - 综合实战工作流
演示如何将四大原则整合到完整的编码流程中
"""
from dataclasses import dataclass, field
from typing import List, Optional, Callable
from enum import Enum
import time

class Principle(Enum):
    THINK_FIRST = "思考先行"
    SIMPLICITY = "极简优先"
    SURGICAL = "精准修改"
    GOAL_DRIVEN = "目标驱动"

@dataclass
class CodingTask:
    """编码任务"""
    description: str
    acceptance_criteria: List[str]  # 验收标准（目标驱动）
    existing_code_context: Optional[str] = None  # 现有代码上下文

@dataclass
class CodingResult:
    """编码结果"""
    code: str
    principles_applied: List[Principle]
    tests_passed: bool
    lines_changed: int
    lines_added: int
    lines_deleted: int

class KarpathyCodingAgent:
    """遵循 Karpathy 四大原则的编码 Agent"""

    def __init__(self):
        self.principles_log: List[str] = []

    def execute(self, task: CodingTask) -> CodingResult:
        """执行编码任务，遵循四大原则"""
        self.principles_log = []

        # 原则 1: 思考先行
        self._think_before_coding(task)

        # 原则 4: 目标驱动执行
        self._define_goals(task)

        # 原则 2: 极简优先 + 原则 3: 精准修改
        code = self._implement(task)

        # 验证
        passed = self._verify(task, code)

        return CodingResult(
            code=code,
            principles_applied=list(Principle),
            tests_passed=passed,
            lines_changed=len(code.split("\n")),
            lines_added=len(code.split("\n")),
            lines_deleted=0,
        )

    def _think_before_coding(self, task: CodingTask):
        """原则 1: 思考先行"""
        self.principles_log.append("【思考先行】分析任务需求...")

        # 检查需求是否清晰
        if not task.acceptance_criteria:
            self.principles_log.append("⚠️  缺少验收标准！请先定义成功标准")
            return

        # 识别潜在假设
        assumptions = self._identify_assumptions(task)
        for a in assumptions:
            self.principles_log.append(f"  假设: {a}")

        # 提出澄清问题（如果有）
        questions = self._generate_questions(task)
        if questions:
            self.principles_log.append("❓ 澄清问题:")
            for q in questions:
                self.principles_log.append(f"  - {q}")

    def _identify_assumptions(self, task: CodingTask) -> List[str]:
        """识别任务中的潜在假设"""
        assumptions = []
        desc = task.description.lower()
        if "api" in desc and "rest" not in desc and "graphql" not in desc:
            assumptions.append("默认使用 REST API 而非 GraphQL")
        if "database" in desc or "db" in desc:
            assumptions.append("假设有数据库连接可用")
        if "async" in desc:
            assumptions.append("假设运行环境支持异步")
        return assumptions or ["无明显假设"]

    def _generate_questions(self, task: CodingTask) -> List[str]:
        """生成需要澄清的问题"""
        questions = []
        if len(task.acceptance_criteria) == 0:
            questions.append("请提供验收标准以定义完成条件")
        return questions

    def _define_goals(self, task: CodingTask):
        """原则 4: 目标驱动执行"""
        self.principles_log.append("【目标驱动】定义可验证目标:")
        for i, criterion in enumerate(task.acceptance_criteria, 1):
            self.principles_log.append(f"  {i}. ✅ {criterion}")

    def _implement(self, task: CodingTask) -> str:
        """原则 2 + 3: 极简优先 + 精准修改"""
        self.principles_log.append("【极简优先】用最少的代码实现功能")
        self.principles_log.append("【精准修改】只实现被要求的功能")

        # 模拟代码实现
        code_lines = [
            f'# Task: {task.description}',
            '',
            'def solve():',
            f'    """{task.description}"""',
            '    # 实现逻辑',
            '    pass',
            '',
        ]
        return "\n".join(code_lines)

    def _verify(self, task: CodingTask, code: str) -> bool:
        """验证是否满足所有验收标准"""
        self.principles_log.append("【目标驱动】验证结果:")
        # 模拟验证
        all_passed = True
        for criterion in task.acceptance_criteria:
            passed = True  # 模拟通过
            status = "✅" if passed else "❌"
            self.principles_log.append(f"  {status} {criterion}")
            all_passed = all_passed and passed
        return all_passed

    def get_principles_log(self) -> str:
        return "\n".join(self.principles_log)


if __name__ == "__main__":
    agent = KarpathyCodingAgent()

    task = CodingTask(
        description="实现用户注册 API，包含邮箱验证和密码强度检查",
        acceptance_criteria=[
            "POST /register 接受 email 和 password",
            "邮箱格式验证（RFC 5322）",
            "密码强度：至少 8 字符，包含大小写和数字",
            "重复邮箱返回 409 Conflict",
            "成功返回 201 Created",
        ],
    )

    result = agent.execute(task)

    print(agent.get_principles_log())
    print(f"\n📊 编码结果:")
    print(f"  代码行数: {result.lines_changed}")
    print(f"  测试通过: {result.tests_passed}")
    print(f"  应用原则: {', '.join(p.value for p in result.principles_applied)}")