Ai Tools Checklist

AI辅助编程 - 工具配置清单与适应框架

创建日期: 2026-01-06 配套文档: ai-assisted-programming-sop-260106.md


🚀 快速启动清单(按优先级排序)

Level 1: 必须立即配置(Day 1)

1.1 核心AI工具

  • Claude Code CLI

    # 安装
    npm install -g @anthropic/claude-code
    
    # 验证
    claude --version
    
    # 配置API密钥
    claude auth login
    
  • IDE集成

    # VS Code
    code --install-extension anthropic.claude-code
    
    # Cursor (可选,替代VS Code)
    # 下载: https://cursor.sh
    
  • API访问

    • Anthropic API密钥
    • 设置使用限额(防止意外超支)
    • 配置重试策略

预计时间: 30分钟


1.2 版本控制增强

  • Git Hooks自动化

    # 安装Husky
    npm install -g husky
    cd your-project
    husky init
    
    # 创建pre-commit hook
    cat > .husky/pre-commit << 'EOF'
    #!/bin/sh
    . "$(dirname "$0")/_/husky.sh"
    
    echo "🔍 运行AI辅助代码检查..."
    npm run lint || exit 1
    npm run test:unit || exit 1
    npm run type-check || exit 1
    
    echo "✅ 所有检查通过"
    EOF
    
    chmod +x .husky/pre-commit
    
  • .gitignore优化

    # AI生成的临时文件
    .ai-cache/
    .ai-temp/
    *.ai-backup
    
    # 敏感信息(永远不要提交)
    .env
    .env.local
    *.key
    

预计时间: 15分钟


1.3 代码质量工具

  • Linter(选择你的语言)

    # Python
    pip install ruff
    # 配置: pyproject.toml
    [tool.ruff]
    line-length = 100
    select = ["E", "F", "W", "I"]
    
    # JavaScript/TypeScript
    npm install -D eslint
    # 配置: .eslintrc.json
    {
      "extends": ["eslint:recommended"],
      "parser": "@typescript-eslint/parser"
    }
    
    # Go
    go install golang.org/x/lint/golint@latest
    
  • Formatter

    # Python
    pip install black
    
    # JavaScript/TypeScript
    npm install -D prettier
    
    # 配置.prettierrc
    {
      "semi": true,
      "singleQuote": true,
      "tabWidth": 2
    }
    
  • 静态分析

    # Python
    pip install mypy pylint
    
    # TypeScript(内置)
    # JavaScript
    npm install -D typescript-eslint
    

预计时间: 45分钟


Level 2: 本周内配置(Day 2-7)

2.1 测试框架

  • 单元测试

    # Python
    pip install pytest pytest-cov
    
    # JavaScript
    npm install -D vitest
    
    # 配置package.json
    {
      "scripts": {
        "test": "vitest",
        "test:coverage": "vitest --coverage"
      }
    }
    
  • 测试覆盖率报告

    # Python
    pytest --cov=src --cov-report=html
    
    # JavaScript
    vitest --coverage
    

预计时间: 1小时


2.2 MCP服务器(Model Context Protocol)

什么是MCP? MCP允许你创建自定义工具,让AI可以访问特定功能(数据库、API、文件系统等)。

  • 核心MCP服务器

    // ~/.claude.json
    {
      "mcpServers": {
        "filesystem": {
          "command": "npx",
          "args": ["-y", "@anthropic/mcp-server-filesystem", "/path/to/allowed/dir"]
        },
        "git": {
          "command": "npx",
          "args": ["-y", "@anthropic/mcp-server-git", "--repository", "/path/to/repo"]
        },
        "database": {
          "command": "npx",
          "args": ["-y", "@anthropic/mcp-server-postgres", "postgresql://user:pass@localhost/db"]
        }
      }
    }
    
  • 自定义MCP服务器模板

    # mcp-mytool/server.py
    from mcp import MCPServer
    from mcp.types import Tool, TextContent
    
    server = MCPServer("my-custom-tool")
    
    @server.tool()
    async def analyze_logs(log_file: str) -> list[TextContent]:
        """分析日志文件并提取关键信息"""
        import re
    
        with open(log_file, 'r') as f:
            logs = f.read()
    
        # 提取错误
        errors = re.findall(r'ERROR: (.+)', logs)
    
        return [TextContent(
            type="text",
            text=f"发现 {len(errors)} 个错误:\n" + "\n".join(errors[:10])
        )]
    
    if __name__ == "__main__":
        server.run()
    
  • 测试MCP服务器

    # 本地运行测试
    mcp dev mcp-mytool
    
    # 在Claude Code中测试
    /claude 使用analyze_logs工具分析app.log
    

预计时间: 2-3小时


2.3 CI/CD集成

  • GitHub Actions工作流

    # .github/workflows/ai-assisted-ci.yml
    name: AI-Assisted CI
    
    on: [push, pull_request]
    
    jobs:
      ai-verify:
        runs-on: ubuntu-latest
        steps:
          - uses: actions/checkout@v4
    
          - name: Setup Node.js
            uses: actions/setup-node@v4
            with:
              node-version: '20'
    
          - name: Install dependencies
            run: npm ci
    
          - name: Run linter
            run: npm run lint
    
          - name: Run type check
            run: npm run type-check
    
          - name: Run tests
            run: npm run test:coverage
    
          - name: AI Code Review (if PR)
            if: github.event_name == 'pull_request'
            run: |
              echo "Triggering AI review..."
              # 这里可以调用AI API进行代码审查          
    
  • 自动化PR审查

    # 创建GitHub Action
    # .github/workflows/ai-pr-review.yml
    name: AI PR Review
    
    on:
      pull_request:
        types: [opened, synchronize]
    
    jobs:
      review:
        runs-on: ubuntu-latest
        steps:
          - uses: actions/checkout@v4
    
          - name: AI Review
            uses:alex-courtis/ai-pr-review@v1
            with:
              anthropic-api-key: ${{ secrets.ANTHROPIC_API_KEY }}
              max-tokens: 4000
    

预计时间: 1.5小时


Level 3: 高级配置(Week 2-4)

3.1 监控与可观测性

  • 性能监控

    // 添加到你的应用
    const perfObserver = new PerformanceObserver((list) => {
      for (const entry of list.getEntries()) {
        console.log(`[PERF] ${entry.name}: ${entry.duration}ms`);
      }
    });
    perfObserver.observe({ entryTypes: ['measure', 'navigation'] });
    
  • 错误追踪

    # Sentry
    npm install @sentry/node
    
    # 配置
    Sentry.init({
      dsn: process.env.SENTRY_DSN,
      tracesSampleRate: 1.0,
    });
    
  • 日志聚合

    # docker-compose.yml
    version: '3'
    services:
      app:
        image: your-app
        logging:
          driver: "json-file"
          options:
            max-size: "10m"
            max-file: "3"
    
      loki:
        image: grafana/loki:latest
        ports:
          - "3100:3100"
    
      promtail:
        image: grafana/promtail:latest
        volumes:
          - /var/log:/var/log:ro
          - ./promtail-config.yml:/etc/promtail/config.yml
    

预计时间: 2-3小时


3.2 文档生成

  • 自动API文档

    # Python
    pip install sphinx sphinx-rtd-theme
    
    # 生成文档
    sphinx-quickstart docs
    sphinx-build -b html docs/ docs/_build/
    
    # JavaScript
    npm install -D typedoc
    typedoc --out docs src
    
  • 架构图自动生成

    # 使用AI生成Mermaid图
    prompt = """
    分析以下代码库,生成:
    1. 系统架构图(Mermaid格式)
    2. 数据流图
    3. 组件依赖关系
    
    代码库结构:
    {repository_structure}
    """
    

预计时间: 1-2小时


🔧 适应框架详细实现

A1框架: 工具执行信号适应

概念: AI根据工具执行结果动态调整策略

实现模板

# tools/adaptive_executor.py
from typing import Callable, Any, Dict
import subprocess
import json

class AdaptiveExecutor:
    def __init__(self):
        self.tool_history = {}
        self.failure_patterns = {}

    async def execute_with_adaptation(
        self,
        primary_tool: Callable,
        fallback_tools: list[Callable],
        context: Dict[str, Any]
    ) -> tuple[bool, Any]:
        """
        执行工具,失败时自动适应

        返回: (success, result)
        """
        # 尝试主工具
        try:
            result = await primary_tool(**context)
            self._record_success(primary_tool.__name__, context)
            return True, result
        except Exception as e:
            error_type = type(e).__name__
            error_msg = str(e)

            # 分析失败模式
            strategy = self._analyze_failure(error_type, error_msg)

            # 根据策略选择适应方案
            if strategy == "retry_with_modified_params":
                modified_context = self._modify_params(context, error_msg)
                return await self.execute_with_adaptation(
                    primary_tool, fallback_tools, modified_context
                )

            elif strategy == "switch_to_fallback":
                for fallback in fallback_tools:
                    try:
                        result = await fallback(**context)
                        self._record_success(fallback.__name__, context)
                        return True, result
                    except Exception:
                        continue

            # 所有策略都失败
            return False, error_msg

    def _analyze_failure(self, error_type: str, error_msg: str) -> str:
        """分析失败原因,返回适应策略"""
        if "timeout" in error_msg.lower():
            return "increase_timeout"
        elif "permission" in error_msg.lower():
            return "escalate_permissions"
        elif "not found" in error_msg.lower():
            return "switch_to_fallback"
        else:
            return "retry_with_modified_params"

    def _modify_params(self, context: Dict, error_msg: str) -> Dict:
        """根据错误信息修改参数"""
        modified = context.copy()

        if "timeout" in error_msg:
            modified["timeout"] = modified.get("timeout", 30) * 2

        return modified

    def _record_success(self, tool_name: str, context: Dict):
        """记录成功模式"""
        key = f"{tool_name}:{json.dumps(context, sort_keys=True)}"
        self.tool_history[key] = self.tool_history.get(key, 0) + 1

使用示例

# 使用A1框架
executor = AdaptiveExecutor()

async def git_push(branch: str):
    subprocess.run(["git", "push", "origin", branch], check=True)

async def git_push_with_force(branch: str):
    subprocess.run(["git", "push", "origin", branch, "--force-with-lease"], check=True)

async def git_push_via_ssh(branch: str):
    subprocess.run(["GIT_SSH=ssh", "git", "push", "origin", branch], check=True)

# 执行(自动适应)
success, result = await executor.execute_with_adaptation(
    primary_tool=git_push,
    fallback_tools=[git_push_with_force, git_push_via_ssh],
    context={"branch": "main"}
)

if success:
    print("✅ Push成功")
else:
    print(f"❌ Push失败: {result}")

A2框架: 代理输出信号适应

概念: AI根据自身输出质量调整后续行为

实现模板

# agents/quality_feedback_agent.py
from typing import List, Tuple
import subprocess

class QualityFeedbackAgent:
    def __init__(self, quality_threshold: float = 0.8):
        self.threshold = quality_threshold
        self.feedback_history = []

    async def generate_with_feedback(
        self,
        generator: Callable,
        prompt: str,
        max_iterations: int = 3
    ) -> Tuple[bool, str]:
        """
        生成代码,根据质量反馈迭代优化

        返回: (success, final_output)
        """
        for iteration in range(max_iterations):
            # 生成输出
            output = await generator(prompt)

            # 评估质量
            quality = await self._evaluate_quality(output)

            print(f"Iteration {iteration + 1}: Quality = {quality:.2f}")

            # 如果达到阈值,返回
            if quality >= self.threshold:
                self._record_success(prompt, output)
                return True, output

            # 否则,生成反馈并重新生成
            feedback = await self._generate_feedback(output, quality)
            prompt = self._refine_prompt(prompt, feedback)

        # 达到最大迭代次数
        return False, output

    async def _evaluate_quality(self, code: str) -> float:
        """评估代码质量(0-1)"""
        score = 0.0
        max_score = 0.0

        # 1. Linting检查
        try:
            result = subprocess.run(
                ["ruff", "check", "--output-format=json", "-"],
                input=code,
                capture_output=True,
                text=True
            )
            if result.returncode == 0:
                score += 0.3
            max_score += 0.3
        except Exception:
            pass

        # 2. 类型检查
        try:
            result = subprocess.run(
                ["mypy", "-", "--no-error-summary"],
                input=code,
                capture_output=True,
                text=True
            )
            if result.returncode == 0:
                score += 0.3
            max_score += 0.3
        except Exception:
            pass

        # 3. 测试通过率
        try:
            # 假设测试已经设置
            result = subprocess.run(
                ["pytest", "-q"],
                capture_output=True,
                text=True,
                timeout=30
            )
            if result.returncode == 0:
                score += 0.4
            max_score += 0.4
        except Exception:
            pass

        return score / max_score if max_score > 0 else 0.0

    async def _generate_feedback(self, code: str, quality: float) -> str:
        """生成改进反馈"""
        feedback = []

        # 运行各种检查工具
        checks = {
            "lint": ["ruff", "check", "-"],
            "type": ["mypy", "-"],
        }

        for check_name, cmd in checks.items():
            try:
                result = subprocess.run(
                    cmd,
                    input=code,
                    capture_output=True,
                    text=True
                )
                if result.returncode != 0:
                    feedback.append(f"### {check_name.upper()} 失败:\n{result.stdout}")
            except Exception:
                pass

        return "\n\n".join(feedback)

    def _refine_prompt(self, original_prompt: str, feedback: str) -> str:
        """根据反馈优化提示"""
        return f"""{original_prompt}

上次尝试的反馈:
{feedback}

请根据这些反馈修复问题。"""

    def _record_success(self, prompt: str, output: str):
        """记录成功模式"""
        self.feedback_history.append({
            "prompt": prompt,
            "output": output,
            "success": True
        })

使用示例

# 使用A2框架
agent = QualityFeedbackAgent(quality_threshold=0.8)

async def code_generator(prompt: str) -> str:
    # 这里调用Claude API
    response = await claude.messages.create(
        model="claude-opus-4-5",
        max_tokens=4000,
        messages=[{"role": "user", "content": prompt}]
    )
    return response.content[0].text

# 生成并迭代优化
success, code = await agent.generate_with_feedback(
    generator=code_generator,
    prompt="写一个Python函数来计算斐波那契数列",
    max_iterations=3
)

if success:
    print("✅ 代码质量达标")
    print(code)
else:
    print("⚠️ 未达到质量阈值,但这是最佳结果")
    print(code)

📋 每日检查清单

早晨启动(5分钟)

  • 打开Claude Code/Cursor
  • 检查今日任务列表
  • 确认AI模型版本(是否有更新)
  • 快速扫描待处理的PR/Issues

工作中(按需)

  • 使用AI前:压缩上下文
  • AI生成后:立即验证
  • 遇到问题:记录到知识库
  • 发现新模式:更新提示模板

晚间复盘(10分钟)

  • 记录今日成就
  • 记录失败案例
  • 更新生产力指标
  • 规划明日任务

🎯 生产力追踪表

每日日志模板

## 260106 工作日志

### 今日任务
- [x] 任务1: XXX (2小时)
- [x] 任务2: XXX (1.5小时)
- [ ] 任务3: XXX (未完成)

### AI使用统计
- 代码生成: 15次
- 调试: 3次
- 代码审查: 5次
- 文档生成: 2次

### 生产力指标
- PR完成: 2个
- 代码行数: 500 (手动: 50, AI: 450)
- Bug修复: 3个
- 学习时间: 1小时

### 关键发现
1. 发现XX任务用AI可节省80%时间
2. 提示模板Y效果最好
3. 工具Z在XX场景下不适用

### 失败教训
- 案例: XXX
- 原因: 提示不够清晰
- 改进: 添加具体示例

### 明日计划
1. 优化XX提示模板
2. 学习YY新技术
3. 完成ZZ任务

🚨 常见问题与解决方案

Q1: AI生成的代码无法运行

症状: 直接运行报错 原因:

  • 上下文不足
  • 约束条件不明确
  • 环境差异

解决:

  1. 提供完整的上下文(依赖、版本、配置)
  2. 明确错误处理要求
  3. 让AI先生成测试,再生成代码

Q2: AI给出错误建议

症状: 建议不符合实际或不安全 原因:

  • AI不了解具体场景
  • 缺少安全约束
  • 幻觉(编造不存在的内容)

解决:

  1. 要求AI提供引用和证据
  2. 添加安全审查步骤
  3. 对关键决策进行人工验证

Q3: 上下文太大,AI无法处理

症状: AI回复"上下文太长"或给出不相关答案 原因:

  • 代码库太大
  • 信息冗余

解决:

  1. 使用/rosetta-experimental-learning skill追踪数据流
  2. 分阶段提供上下文(先架构,再细节)
  3. 使用外部化规格(文档、图表)

Q4: AI修改了不该改的代码

症状: AI修改了其他功能 原因:

  • 任务边界不清晰
  • 缺少负样本

解决:

  1. 明确"只修改XXX,不要动YYY"
  2. 提供测试验证范围
  3. 使用Git diff人工审查

📚 进阶学习资源

每月学习计划

Month 1: 基础掌握

  • Week 1: 熟悉Claude Code基础功能
  • Week 2: 掌握提示工程
  • Week 3: 学习适应框架(A1/A2)
  • Week 4: 完成一个小项目

Month 2: 进阶技巧

  • Week 1: 开发自定义MCP服务器
  • Week 2: 集成CI/CD
  • Week 3: 建立知识库
  • Week 4: 优化工作流

Month 3: 规模化应用

  • Week 1: 团队协作最佳实践
  • Week 2: 多agent协作
  • Week 3: 性能优化
  • Week 4: 开源贡献

推荐阅读顺序

  1. Claude Code官方文档 - 了解所有功能
  2. “Attention Is All You Need” - 理解Transformer基础
  3. “Sparks of AGI” - 了解LLM能力边界
  4. Stanford HAI论文 - AI辅助工程框架
  5. Anthropic技术博客 - 最新研究进展

✅ 配置验证脚本

#!/bin/bash
# verify-ai-setup.sh - 验证AI工具配置

echo "🔍 验证AI辅助编程环境..."

# 1. Claude Code
if command -v claude &> /dev/null; then
    echo "✅ Claude Code: $(claude --version)"
else
    echo "❌ Claude Code未安装"
fi

# 2. Git
if command -v git &> /dev/null; then
    echo "✅ Git: $(git --version)"
else
    echo "❌ Git未安装"
fi

# 3. Python工具(如果适用)
if command -v python3 &> /dev/null; then
    echo "✅ Python: $(python3 --version)"

    if command -v ruff &> /dev/null; then
        echo "✅ Ruff: $(ruff --version)"
    fi

    if command -v mypy &> /dev/null; then
        echo "✅ MyPy: $(mypy --version)"
    fi
fi

# 4. Node工具(如果适用)
if command -v node &> /dev/null; then
    echo "✅ Node: $(node --version)"

    if command -v eslint &> /dev/null; then
        echo "✅ ESLint: $(eslint --version)"
    fi
fi

# 5. MCP配置
if [ -f ~/.claude.json ]; then
    echo "✅ MCP配置文件存在"
    # 可以添加更多检查
else
    echo "⚠️ ~/.claude.json不存在"
fi

echo "✨ 验证完成!"

总结

这份清单提供了完整的工具配置和适应框架实现。关键要点:

  1. 渐进式配置: 从Level 1开始,逐步添加
  2. 自动化优先: 能自动化的都自动化
  3. 持续验证: 每个配置都要验证可用性
  4. 记录学习: 建立个人知识库

下一步:

  1. 运行verify-ai-setup.sh验证当前环境
  2. 从Level 1开始配置
  3. 完成30天行动计划
  4. 分享你的经验和方法