上周末早上，我手机弹出一条飞书消息：“上海今日有雨，记得带伞”。这是我刚用Claude Code从零搭出来的天气提醒机器人在准点播报。算了一下，从初始化项目到收到这条真实通知，前后不到半天。更让我意外的是，这半天里真正由我手写的代码不超过二十行，剩下的全是Claude Code根据我的需求描述补全的——整个开发工作流的节奏，和我过去习惯的完全不一样了。如果你也想体验AI辅助开发，想看看Claude Code到底怎么融入日常开发，又不愿意从 hello world 级别的demo开始，那我建议你拿“天气提醒机器人”这个项目来开刀。这篇文章会把我的完整过程拆开讲：环境配置、核心代码、定时部署，外加一次凌晨三点排错的完整复盘。

1. 为什么偏偏选“天气提醒机器人”当第一个Claude Code项目

很多人第一次接触Claude Code，会想让它写个商城、写个后台管理系统，结果对话半小时还在搭框架，最后不了了之。我当时的判断是：天气提醒机器人这种体量的项目，才是验证AI开发工作流的最佳样本。

1.1 项目边界清楚，才知道AI在帮你干什么

一个天气提醒机器人，拆开看无非三块：

• 拉天气数据：调用天气API，拿到当前或当天的预报；
• 做判断：根据温度、降水概率等字段，决定要不要提醒、提醒什么内容；
• 发通知：通过飞书机器人、邮件或微信渠道推给用户。

每块都有明确的输入输出。数据源的返回结构是公开的，通知发送成功与否一眼能看出来，判断逻辑就是几条if语句。项目有没有做完，不需要别人验收，自己跑一次就知道。

这种“边界清楚”的项目，特别适合用来观察Claude Code的行为模式。你给它一个需求，它会自己整理步骤、选库、写函数，甚至把异常处理都补上。你能很清楚地区分哪些是它写的、哪些需要你插手，从而建立对AI辅助开发的直觉判断。如果一上来就丢给它一个模糊的“帮我做个平台”，它也会迷茫，你更无从判断它的能力边界。

1.2 外部依赖丰富，反而更适合练手

这个项目好玩就好玩在：它要接两个外部系统——天气API和消息推送。外部依赖多，意味着你需要实实在在处理API鉴权、返回结构解析、超时与重试，这些才是真实开发里天天遇到的东西。

我当时选的是和风天气API的免费开发者版。理由有两个：一是申请key的流程简单，注册完就能用；二是返回字段里有我需要的温度、天气现象、降水概率，直接对应机器人要做的“判断”。如果你不在国内或者有其他偏好，换成OpenWeatherMap也一样，Claude Code对这类文档化良好的API理解力都很强。

通知通道我选了飞书自定义机器人Webhook。原因是免费、配置快、调试直观——往一个URL上POST一段JSON，群里立刻有反应。作为第一个版本，反馈速度比什么技术栈都重要。

这一阶段我最想让你记住的不是技术选型本身，而是选型逻辑：项目要能快速看见成果，同时逼你去处理真实工程问题。天气提醒机器人恰好同时满足这两点。

2. 先把环境立起来：安装、认证与模型接入

工欲善其事，必先利其器。Claude Code虽然以“对话式开发”闻名，它的本质还是一个命令行工具。环境配好了，后面所有流程才顺。

2.1 安装命令和版本验证（Linux与Windows）

安装Claude Code最省心的一条路是npm。前提是你机器上有Node.js，建议18以上版本。命令很简单：

npm install -g @anthropic-ai/claude-code

装完验证一下：

claude --version

如果能打印出版本号，说明安装成功。如果你用的是Ubuntu这类Linux环境，也可以走apt、官方脚本等方式，但实测下来npm最不容易出幺蛾子，因为后续升级也是同一套命令。

Windows上同样用npm，装了之后建议在PowerShell里跑claude命令。如果你习惯VS Code，后面我会单独讲插件的配置方式。Windows用户最常遇到的两个报错，一个是claude: 无法识别，说明npm全局安装路径没加到PATH；另一个是提示找不到Node，先确认node -v能正常输出再重装。

2.2 认证、密钥与settings.json配置

安装只是第一步，真正卡住不少人的是认证。Claude Code运行时需要一个可以访问Anthropic API的身份凭证。两个方式：一是登录Claude账号走订阅授权，二是直接配置ANTHROPIC_API_KEY环境变量。

我选择的是API Key方式，原因很实际：API Key可以单独配置、单独撤销，而且方便后续切换到其他兼容模型时排查问题。设置方式：

export ANTHROPIC_API_KEY=你的key

想永久生效就写进~/.bashrc或~/.zshrc，Windows上则在“系统环境变量”里加同名的用户变量。配好之后重新打开终端，让变量生效。

接下来是重点：settings.json。Claude Code允许你通过配置文件控制它的行为，默认位置在~/.claude/settings.json，也可以在项目目录下放一份.claude/settings.json，后者优先。我项目里用到的配置大概长这样：

{ "permissions": { "allow": [ "Read", "Glob", "Bash(npm:*)", "Bash(python:*)", "Edit" ], "deny": [] }, "model": "claude-sonnet-4-0", "includeCoAuthoredBy": true }

这里的permissions是权限控制，别看它不起眼，实际用起来能帮你少踩一大堆坑。你可以限制Claude Code只能执行哪些命令、只能编辑哪些文件，避免它在你不知情的情况下把系统配置改得乱七八糟。我第一次没设权限，让它自己跑一个项目，结果它顺手改了我的全局npm配置，虽然能回滚，但确实吓一跳。所以从现在开始，只要新建项目，我都会把权限规则写在配置文件里。

2.3 VS Code插件与第三方模型接入

如果你习惯在编辑器里干活，Claude Code也有VS Code插件。装好后，侧边栏会多出一个会话面板，可以直接选中代码、右键发送给Claude Code。这一步的作用不是替代终端，而是把AI生成的代码和你的文件对比变得更直观。插件也读取同一套settings.json，所以终端里配好的权限和模型，编辑器里保持一致。

至于第三方模型接入，比如把Claude Code接到DeepSeek或其他兼容模型上，本质就是覆盖API地址和模型名。环境变量可以这样配：

export ANTHROPIC_BASE_URL=https://compatible-endpoint.example.com export ANTHROPIC_MODEL=deepseek-chat

需要说清楚的是，这种做法要求第三方提供Anthropic兼容接口，或者你自己架一个适配层。我实际试过把轻量任务切到第三方模型跑，日常写写脚本没问题，但涉及到复杂重构、安全审查类任务，我还是切回官方Claude系列。把工具链搭好，比盲目追新更重要。这个项目里，我全程用Claude Code官方模型，第三方接入留到后续做成本优化时再试。

3. “提需求”式开发：Claude Code生成核心代码的完整过程

环境配好之后，真正的重头戏才开始。我给你的建议是：别把Claude Code当成搜索引擎，把它当成一个随时待命、而且愿意读你整个仓库的工程师。你的输入是需求描述，不是命令清单。

3.1 我给的原始需求描述

在项目目录下执行claude进入交互界面，我贴的第一段需求是这样的：

帮我用Python写一个天气提醒机器人。需求： 1. 从和风天气API拉取指定城市的今日天气，城市列表从config.json读取； 2. 如果今日有降水（雨、雪、雨夹雪等），通过飞书自定义机器人Webhook发送提醒； 3. 如果没有明显降水，但温度低于5度，也要发一条提醒注意保暖； 4. 提醒文案需要包含城市、温度、天气现象、建议； 5. API key、飞书webhook地址都从环境变量读取，不要硬编码； 6. 生成requirements.txt。

这段描述没有特别炫技，但它把输入、输出、判断规则、敏感信息处理方式都讲清楚了。Claude Code拿到后，没有直接甩给我一段代码，而是先确认了和风天气API的接口格式，然后生成了项目文件结构。我记得它第一版输出了weather_bot.py、config.json、requirements.txt三个文件，代码可运行，结构干净。

这给我一个很深的感受：需求描述越接近“验收标准”，AI生成的代码越接近你想要的东西。别只说要做什么，要连“怎么算成功”一起说清楚。

3.2 拉取天气数据的核心实现

和风天气的免费API返回的是嵌套JSON，Claude Code生成的拉取函数比我自己手写的还要谨慎。它的核心逻辑大致是这样的：

import os import json import requests from typing import Dict, Any def fetch_weather(city: str, config: Dict[str, Any]) -> Dict[str, Any]: """拉取指定城市的实时天气，返回精简后的字段""" api_key = os.getenv("QW_WEATHER_API_KEY") if not api_key: raise RuntimeError("missing QW_WEATHER_API_KEY env") base_url = "https://devapi.qweather.com/v7/weather/now" response = requests.get( base_url, params={"location": city, "key": api_key}, timeout=10 ) response.raise_for_status() payload = response.json() if payload.get("code") != "200": raise RuntimeError(f"weather api error: {payload}") now = payload["now"] text = now.get("text", "未知") temp = float(now.get("feelsLike", "0")) precip = now.get("precip", "0") return {"city": city, "text": text, "temp": temp, "precip": float(precip)}

注意它主动做了几件事：检查环境变量是否存在、请求设置了timeout、对API返回码做了校验，还把寒冷字段、降水字段统一转成float。这些细节如果你不主动提，容易成为AI生成代码的盲区，但Claude Code在第一版就带上了。原因也不玄，它训练时见过太多天气API的接入代码，知道这类接口的常见坑。

3.3 飞书机器人通知与邮件双通道

通知模块是机器人能不能“被收到”的关键。飞书自定义机器人Webhook最基础的使用方式就是POST一个JSON对象到指定URL。Claude Code生成的发送函数还额外加了一个可选签名校验——Webhook地址里带secret的时候，需要在请求头里带上X-LC-Sign。

import hashlib import base64 import hmac import time import requests def send_feishu(webhook: str, content: str, secret: str = "") -> None: """发送文本消息到飞书群""" if secret: timestamp = str(int(time.time())) string_to_sign = f"{timestamp}\n{secret}" sign = base64.b64encode( hmac.new( string_to_sign.encode("utf-8"), digestmod=hashlib.sha256 ).digest() ).decode("utf-8") sign_data = {"timestamp": timestamp, "sign": sign} else: sign_data = {} payload = { "msg_type": "text", "content": {"text": content}, **sign_data, } response = requests.post(webhook, json=payload, timeout=8) response.raise_for_status()

我在配置里同时留了邮件出口作为备用通道，用smtplib包一层。理由很现实：万一飞书群需要维护或者webhook失联，机器人不能跟着哑掉。双通道带来的额外复杂度不大，但关键时刻能救命。

3.4 让Claude Code自己给你讲代码

我在这轮开发里学到的另一个技巧是：让Claude Code解释它自己写的代码，而不是急着往下加功能。只需要在对话里输入 “逐行解释一下fetch_weather这个函数，尤其是异常处理部分”，它会顺着代码路径把每个分支的目的说清楚。

这个习惯帮我提前发现了一个问题：它用的是“体感温度”而非“气温”来判断冷暖，而这其实正是我想要的，冷热提醒按体感走更准确。如果没问它这一句，我大概率会把它当bug改回去。不要默认AI写的都是你想要的，但也别默认AI写的是错的。追问一下，是最快的校验方式。

4. 工作流重塑：开发节奏从“写代码”变成“审代码”

代码跑通之后，我开始认真思考Claude Code对工作流的影响。如果你长期用传统IDE写代码，第一次适应“对话式开发”会有一种很奇妙的不安感：鼠标不再在文件里逐行游走，而是在终端里不断提出需求、审查diff、纠正方向。这种节奏调整，带来的效率变化是实打实的。

4.1 第一次“整文件生成”带来的震撼

传统开发流程里，写一个新功能通常要经历：查文档、建目录、写接口、写模型、写测试、调试联调。每一步之间都有上下文切换成本。我在这个天气项目里的流程却是：说清需求，Claude Code直接生成整文件，然后我一条条看diff。

为了说明差异，我列一个对照表：

最舒服的是改需求。比如某天我想把“降水提醒”改成“降水或风力大于5级都提醒”，命令是：让Claude Code先搜索现有判断逻辑，然后给出影响范围，再动手改。它会在改动前列出涉及的文件和测试点，相当于帮你过了一遍静态检查。这比我过去用IDE全局搜索来得高效得多。

4.2 1M上下文与Skills怎么用才不浪费

Claude Code有个很夸张的上下文能力，实测塞进一个小型项目仓库完全没有问题。天气机器人这种体量，把全部代码、配置文件、README一次性放进上下文中，它也能记住来龙去脉。这意味着你后面发出任何一个指令，它都带着整个项目的内容在做判断，省去了“你把那个文件里的逻辑再讲一遍”的尴尬。

但上下文大不等于可以放手不管。我建议你善用“Skills”机制——它允许你把常用的指令打包成项目级命令。比如我给天气机器人定义了一个skill叫“天气需求变更”，内容是：修改天气参数时，先定位配置文件、再修改weather_bot.py、最后更新README中的参数说明。这样一来，后续我只需要输入那条skill名，Claude Code就会自动执行“定位、修改、同步文档”这个三步流程。

4.3 思考等级与Workflows：复杂任务的分步推进

另外要提一下Claude Code的思考等级参数。日常小改动，比如“把日志加上中文前缀”，我用默认等级就能搞定；但遇到“把通知模块从飞书扩展到企业微信，同时保证不重复通知”这种涉及多处代码的任务，我会用claude --thinking xhigh这样的参数提高思考等级。高等级下它会更谨慎地拆解任务、列出风险点，代价是响应变慢，但值。

这种“按任务复杂度调整思考投入”的做法，其实可以外化成workflows。我的习惯是：把一套完成某个业务目标的对话路径固化下来，让Claude Code分步执行。天气机器人从开发到上线，我就是按“搭建骨架 → 实现API接入 → 实现通知 → 配置定时调度 → 写出部署说明”这五步推进的。每一步之间我会检查diff，确认没有跑偏再进入下一步。整体感受像在做一场微妙的结对编程：它动手，我掌舵。

5. 无人值守不是把程序丢给cron那么简单

机器人代码写完了，本地跑一遍也正常。但“能跑”和“无人值守地跑”是两个完全不同的概念。天气提醒机器人要让人觉得可靠，就得定时触发、失败重试、还要防止重复通知。

5.1 cron与Windows任务计划程序的实际差别

我先在Linux服务器上部署。由于这是Python脚本，定时触发我用的是crontab。下面是我配置的定时任务：

0 7 * * * cd /opt/weather-bot && /usr/bin/python3 weather_bot.py >> logs/weather.log 2>&1

这行的意思是每天早晨7点整，先进入项目目录，再执行天气脚本，标准输出和错误输出都追加到日志文件。注意我写的是绝对路径/usr/bin/python3，而不是python3，因为cron执行环境不受用户环境变量影响，直接写命令名容易触发“找不到命令”的坑。

Windows上则是任务计划程序。创建基本任务，触发器选“每天”，时间设成7点，操作指向python.exe，参数填脚本完整路径，起始目录填项目根目录。这里最容易踩的坑有两个：一是python.exe如果你没有勾选“使用绝对路径”，系统可能找不到；二是任务计划程序有自己的权限上下文，如果脚本需要读环境变量，建议在任务设置里手动填一遍，或者让脚本内部加载一个.env文件。

5.2 日志、重试与防重复通知

定时任务跑起来后，日志就是你的第一道防线。我给脚本入口加了一个简单的日志模块，每次执行都记录：执行时间、拉取到的城市列表、判断结果、通知是否发送成功。

重试逻辑也必须有。天气API偶尔会超时，飞书Webhook也可能短暂不可用。我给请求层统一加上重试策略：最多重试2次，间隔3秒，且只在网络异常时重试，API返回业务错误码则不重试。

最后是防重复通知。定时任务每天只跑一次，理论上不会重复，但实际开发中你会反复手动跑脚本做测试。如果不加任何保护，每手动跑一次，群里的通知就多发一遍。我的做法是加一个“通知去重文件”：记录当天已经通知过的城市列表，如果脚本在同一天再次运行，且某城市已经通知过，就直接跳过发送。

from pathlib import Path sent_log = Path("/tmp/weather_bot_sent.json") def already_notified(city: str, today: str) -> bool: if not sent_log.exists(): return False data = json.loads(sent_log.read_text(encoding="utf-8")) return data.get("date") == today and city in data.get("cities", []) def mark_notified(city: str, today: str) -> None: if sent_log.exists(): data = json.loads(sent_log.read_text(encoding="utf-8")) else: data = {"date": today, "cities": []} data["date"] = today if city not in data["cities"]: data["cities"].append(city) sent_log.write_text(json.dumps(data), encoding="utf-8")

这段逻辑不复杂，但它把“每天最多通知一次”这个业务规则真正落地了。没有这层防护的机器人，迟早会在某次重复调度中让你在群里社死。

6. 一次“凌晨三点连发三条通知”的排查全记录

如果你觉得前面都是顺利时刻，那接下来这个坑，会让你对自动化工具保持清醒。在我把机器人部署到服务器后的第三天，群里在凌晨三点疯狂弹出三条天气提醒。所有人都很懵，因为定时任务明明设的是早晨7点。

6.1 现象与第一反应

凌晨3:00，飞书群收到三条几乎相同的消息：城市、温度、提醒文案一模一样。第一次收到还能解释为测试，连续三次就一定是逻辑问题了。

我的第一反应不是去改代码，而是先冷静记录现象：三条消息间隔多久、内容是否完全一致、有没有从日志里看到重复执行痕迹。这里给你一个排查原则：先把现象收集完整，再做任何改动。很多隐蔽bug之所以难定位，就是因为排查者一上来就改了代码，把现场破坏了。

6.2 链路排查：crontab、日志、代码逐个过

第一步，检查crontab。执行crontab -l后发现，系统里居然有两条任务：一条是原来的0 7 * * *，另一条是我当天下午测试新版配置时留下的一条0 3 * * *，而且两条都把输出写进同一个日志文件。为什么会有第二条？回想起来，当时为了让某个变更尽快验证，我临时改了计划任务，验证后又没删干净。这是典型的“临时操作没有收尾”事故。

第二步，看日志。日志里凌晨3点确实有三次执行记录。一次来自那条残留的cron任务，另外两次则是脚本内部的重试机制在作怪。因为凌晨网络状态不稳，前两次发送飞书消息时都碰到了超时，触发了我之前配置的2次重试。于是：一次调度加上两次重试，三条完全一样的消息。

第三步，定位到推送函数。问题并不在推送代码本身，而在于“重试”和“调度”叠加时，缺少了我在第5章提到的防重复通知保护。日志文件路径我知道，但去重文件的工作目录在cron里变成了/，导致sent_log.exists()一直判断为False，去重机制完全失效。

到这里结论清晰了：残留的cron任务 + 网络超时重试 + 去重状态文件路径失效，三个问题叠加才导致三连发。

6.3 修复、去重与自动化配置的教训

修复分三步。第一，立刻删除残留的cron任务，让调度回到唯一正确的时间点；第二，修改脚本，让日志和状态文件都使用绝对路径，不再依赖“当前工作目录”；第三，把重试机制从“发送函数内部”改成“统一在调度入口控制”：即只有调度任务触发的执行才允许重试，手动执行则每次只发一次，方便测试。

import os BASE_DIR = os.path.dirname(os.path.abspath(__file__)) sent_log = Path(BASE_DIR) / "data" / "sent.json"

这段代码解决的问题，是让我不再依赖cron设置的起始目录。脚本无论被谁调用，都能稳定找到自己的状态文件。

这轮排错给我最大的教训不是不要配错cron，而是要尊重“操作留痕”。所有对生产环境的临时改动，都应该通过CLI工具记录；如果手滑留下了多余配置，也要立即清理。Claude Code能帮你生成命令、补全配置，但它不会替你判断“这条命令是否应该长期存在”。自动化工具越强，人的审查责任反而越重。

排完这个坑之后，我又把同样的防护逻辑补到了邮件通知通道。现在这台天气机器人在服务器上安安稳稳跑了好几周，每天早上7点准时出现，遇到已经通知过的城市绝不多说一句废话。我自己实操下来最大的感受是：让AI写代码、做配置，可以很爽；但让AI做主流程的设计决策、承担运维结果的最后一道审查，这件事现阶段必须留在人手里。一个可靠的开发工作流，是让Claude Code去做它擅长的快速产出，而你专注做它暂时做不到的边界判断和复盘。