这次我们来看一个具体案例用 Claude Code 搭建一套农业物联网监测平台。Claude Code 是 Anthropic 推出的命令行 AI 编程工具它不只是帮你补全代码而是可以直接在终端里理解需求、读写项目文件、执行命令、跑测试相当于一个能动手改代码的 AI 开发助手。农业物联网这个案例有意思的地方在于它不是一个简单的 CRUD 练习而是把设备接入、数据采集、实时展示、异常告警串成一条完整链路正好能检验 AI 编程 Agent 能不能从零把一个系统搭起来。本文会围绕“Claude Code 100 个案例”这个主线以农业物联网监测平台作为实操目标给出从环境准备、安装启动、分阶段编码、效果验证到接口调用和自动化批量任务的完整流程。我不会只讲概念重点是你照着操作能否跑通以及遇到问题怎么排查。如果你正在关注 Claude Code 怎么落地真实项目或者准备做 IoT 方向的小型平台这篇文章可以直接收藏。1. Claude Code 核心能力速览先把 Claude Code 本身的能力和本次农业物联网案例的定位放在一张表里方便快速判断这个工具适不适合你。能力项说明工具类型命令行 AI 编程 Agent由 Anthropic 推出主要能力理解自然语言需求、读写项目文件、执行终端命令、生成并修改代码、运行测试、管理多文件工程使用方式终端交互模式claude单次任务模式claude 任务描述--print输出结果依赖环境需要 Node.js 18 及以上通过 npm 全局安装认证方式Anthropic 账号登录或配置 API Key具体以你的账号权限为准项目规则通过项目根目录的 CLAUDE.md 约定技术栈、目录结构和编码规范是否支持批量任务支持可用非交互模式接入脚本、CI 或定时任务是否支持 API 调用支持命令行输出 JSON 或纯文本便于程序消费适合场景原型开发、中小型系统搭建、代码重构、测试补充、自动化脚本生成本次案例目标用 Claude Code 搭建农业物联网监测平台覆盖采集、存储、展示、告警四个环节从工具角度看Claude Code 会把“需求 项目规则 当前文件状态”统一放进上下文然后通过工具调用完成文件修改和执行命令。这套机制决定了它适合做多文件工程而不只是单文件的代码生成。农业物联网监测平台恰好是多模块项目适合拿出来当一个完整的 Agent 工作流示范。2. 农业物联网监测平台要解决什么问题农业物联网监测平台的核心需求可以拆成四块传感器数据采集、数据存储与管理、实时可视化监控、异常阈值告警。典型的场景是温室大棚里部署温度、湿度、土壤水分、光照等传感器数据通过 MQTT 或 HTTP 上报到平台平台把这些数据存下来在 Web 页面上展示实时曲线遇到温度过高、土壤过干等异常时触发告警。用 Claude Code 来搭这套系统重点不是让 AI 一次性吐出所有代码而是把它当成一个能持续沟通的工程助理。你可以先让它搭骨架再逐步补充数据模型、采集接口、前端页面和告警规则每一步都能运行验证后再进入下一步。这样做的好处是AI 生成的内容始终处于可运行状态而不是一个看起来很完整却跑不起来的代码堆。这个案例适合谁适合想了解 AI 编程 Agent 如何参与真实项目开发的开发者适合需要快速搭建 IoT 原型在做毕设或内部展示的学生和工程师也适合想验证 Claude Code 是否能替代部分重复编码工作的人。不适合的场景是直接把 AI 生成的代码部署到生产温室控制系统中不做审查这风险太高另外如果涉及真实农场的地理位置、产量、经营数据必须先处理数据合规和访问权限不能为了演示随意采集真实数据。在合规和隐私方面要特别强调本文所有内容都围绕本地开发测试展开不要用公网开放访问你的农业平台。涉及设备控制、自动化灌溉、卷帘电机等执行操作时必须做人工授权和操作审计不能让 AI 生成的接口直接控制实体设备。3. Claude Code 环境准备与前置条件在开始搭建农业物联网平台之前先把 Claude Code 的运行环境准备好。整个链条并不复杂但 Node 版本不对会直接导致安装失败。第一操作系统。Windows、macOS、Linux 都可以跑 Claude Code下面命令在 Windows 上建议通过 PowerShell 或 Git Bash 执行macOS/Linux 直接在终端执行。本文以类 Unix 环境为主Windows 用户只需要把命令中的路径和环境变量写法按系统习惯调整一下。第二Node.js 版本。Claude Code 是 npm 包要求 Node.js 18 及以上。先检查当前版本node -v npm -v如果版本过低建议用 nvm 安装较新的 Node LTS 版本不要把系统自带的 Node 环境弄乱。这一步如果没做对后面安装 Claude Code 会出现各种模块加载错误排查起来很浪费时间。第三IDE 或终端。你可以直接在系统终端里用 Claude Code也可以在 VS Code 的终端里使用。如果你习惯图形界面在 VS Code 中打开项目目录然后调出终端运行claude即可。VS Code 的好处是能实时看到 AI 修改文件的 diff方便 review。第四认证准备。Claude Code 启动后通常需要登录 Anthropic 账号或者通过ANTHROPIC_API_KEY环境变量配置 API Key。团队或组织账号如果禁用了 Claude 订阅访问 Claude Code需要联系管理员确认权限或改用 API Key 方式。# 设置 API Key实际 Key 需要替换为你自己的 export ANTHROPIC_API_KEYsk-你的key如果你使用的是兼容接口或第三方模型网关需要把ANTHROPIC_BASE_URL等环境变量一并配置好并确认模型名和接口格式与当前 Claude Code 版本兼容。4. Claude Code 安装与启动方式Claude Code 的安装很简单npm 全局安装一条命令npm install -g anthropic-ai/claude-code安装完成后确认版本claude --version如果以后需要更新执行claude update启动方式分两种。第一种是交互模式进入项目目录后直接运行claude然后在终端里用自然语言描述需求。第二种是单次任务模式直接传入提示词适合脚本化调用# 交互模式 cd farm-iot claude # 单次任务模式生成 README claude 为当前项目生成一个 README.md包含项目简介和启动方式在交互模式里有一些常用操作需要记住/init可以初始化项目上下文/add-dir可以把目录加入上下文/compact可以压缩过长的上下文/clear清空当前对话/status查看当前状态。如果上下文太长导致生成质量变差优先用/compact不要盲目新开对话。启动后Claude Code 会在项目目录下自动管理工作文件。为了让它更好地理解你的需求我建议在项目根目录创建CLAUDE.md把技术栈和约束写进去。下面是一份农业物联网项目的规则示例# CLAUDE.md ## 项目目标 构建一个农业物联网监测平台覆盖传感器数据采集、存储、可视化与告警。 ## 技术栈 - 后端Python FastAPI - 数据库SQLite开发/ PostgreSQL生产 - 前端Vue 3 Vite ECharts - 传输协议MQTT备选 HTTP API - 认证开发阶段可跳过生产必须接入登录鉴权 ## 项目约束 - 生成的代码必须提供启动方式说明 - 敏感配置统一放 .env不要写入代码 - 设备控制类接口必须添加权限校验CLAUDE.md的作用是让 AI 在每次生成代码时都遵守这些约定。没有这个文件Claude Code 只能靠当前对话的上下文一旦会话变长就容易偏离方向。5. 用 Claude Code 搭建农业物联网平台分阶段实操这一部分是重点。我会把整个搭建过程拆成四个阶段每个阶段都给出提示词示例、预期产物和验证方式。建议你按阶段执行不要一次性让 Claude Code 生成全部代码否则后面排错会非常痛苦。5.1 阶段一初始化项目骨架第一个阶段的目标是跑通一个最小可运行的前后端骨架。不要一上来就加入传感器、数据库、MQTT 等复杂功能。在空目录farm-iot下启动 Claude Code 后输入我们在当前目录搭建农业物联网监测平台。请先初始化项目骨架 1. 后端使用 Python FastAPI提供 /health 健康检查接口 2. 前端使用 Vue 3 Vite首页显示系统状态卡片 3. 开发阶段先不用数据库页面数据用 mock 4. 生成启动说明 README.md 5. 完成后再告诉我如何启动和验证预期产出是一个包含backend和frontend子目录的项目骨架。这里要重点验证两件事后端能否启动并返回健康检查信息前端能否启动并显示页面。不要继续往后做功能先把两个服务跑通。如果 Claude Code 在生成过程中使用了虚拟环境或 npm 安装依赖注意看终端输出是否成功。这一步常见的坑是 Python 版本和 Node 版本不匹配后续我在第九章统一说明排查方法。5.2 阶段二传感器数据采集与设备管理骨架跑通后进入核心业务开发。这个阶段要完成三件事设备管理的数据模型、模拟传感器数据上报、Rest API 接口。继续在 Claude Code 交互中提示在现有骨架上增加物联网数据模块 1. 定义 Device 模型字段包括 id、name、location、sensor_types、status 2. 定义 SensorRecord 模型字段包括 device_id、sensor_type、value、unit、created_at 3. 开发阶段使用 SQLite 存储用 SQLAlchemy 管理 4. 提供设备注册、设备列表、传感器数据写入、传感器数据查询接口 5. 写一个 simulator/sensor_sim.py模拟温湿度数据定时上报 6. 完成后给出接口文档和启动步骤如果这一阶段生成顺利你会看到一个具备基础 CRUD 能力的后端同时有一个模拟传感器数据的脚本。这里建议让 Claude Code 顺便生成一个docs/api.md把接口的作用、参数和返回示例记录下来。这个文档后面无论是自测还是接入前端都非常有用。验证方式先启动后端然后单独运行传感器模拟脚本最后通过接口查询数据。例如# 查询设备列表 curl http://127.0.0.1:8000/api/devices # 查询某个设备最近的温湿度数据 curl http://127.0.0.1:8000/api/devices/1/records?limit20这个阶段最值得检查的是数据模型设计是否合理传感器类型是否可扩展时间字段是否带时区设备状态是否便于后续做在线离线判断。如果发现 AI 生成的数据模型有缺陷直接让它修改不用自己动手。5.3 阶段三实时监测与可视化数据已经能写入接下来把它展示出来。这个阶段引入 WebSocket 和 ECharts。在现有基础上增加实时监测页面 1. 后端增加 WebSocket 接口用于向前端推送最新传感器数据 2. 传感器模拟脚本改为持续上报并支持多个设备 3. 前端增加实时曲线页面用 ECharts 展示温度和湿度变化 4. 如果没有新数据页面不要闪烁保持稳定 5. 完成后说明如何同时启动后端、模拟器和前端进行联调这里建议让 Claude Code 把模拟器改成可以指定设备数量和上报频率方便后续测试实时性。当前端实时曲线能随模拟数据滚动时这个阶段就算通过。联调过程中要注意WebSocket 的地址不能写死端口和路径要和后端配置一致。如果页面里没数据优先查看浏览器开发者工具里的网络请求和 WebSocket 连接状态再回过头看后端日志。5.4 阶段四告警规则与阈值触发最后一个核心功能是告警。农业物联网平台的告警逻辑通常不复杂但对工程化要求比较高。增加告警模块 1. 支持为设备配置告警规则例如当 temperature 大于 35 或 soil_moisture 小于 30 时触发 2. 后端在写入传感器数据时判断规则触发后生成 AlertRecord 3. 提供告警记录查询接口支持按设备、规则、时间范围筛选 4. 模拟器里故意产生一条温度越界数据验证告警能触发 5. 前端告警页面展示最新告警列表和状态这一阶段判断成功的关键是端到端能跑通设备注册、模拟数据写入、规则匹配、告警生成、前端展示。除了正常流程还要检查异常流程比如阈值配置错误时接口是否会返回明确报错避免埋雷。告警模块做完后这个农业物联网监测平台的 MVP 就成立了。如果你还想继续扩展可以让 Claude Code 增加历史数据统计、批量导出 CSV、日报生成等能力这些放在批量任务章节讲。6. 功能测试与效果验证AI 生成的代码如果不做系统性验证很容易出现“看起来对跑起来错”的情况。建议按照下面的测试维度逐项验证。第一基础生成能力测试。分别测试设备注册、数据写入、数据查询三个核心接口确认接口能通返回字段符合预期。第二实时推送测试。启动多个模拟传感器后确认 WebSocket 能持续推送数据前端不再依赖手动刷新。第三告警触发测试。将某个设备的温度阈值调到很低比如 10 度然后让模拟器上报 30 度确认告警记录能被创建并展示。第四批量数据测试。用脚本一次性写入 1000 条传感器数据观察接口响应时间和页面加载是否正常。这个测试不需要很高的并发量重点是确认数据库设计和查询语句没有明显性能问题。第五异常输入测试。提交不存在的设备 ID、空数据、超大数值确认接口能返回清晰的错误信息而不是直接 500。如果你不想手工点接口可以让 Claude Code 生成一套 pytest 测试用例。提示词可以这样写为当前后端项目生成 pytest 测试 1. 测试设备注册、列表、详情接口 2. 测试传感器数据写入和查询 3. 测试告警规则触发逻辑 4. 测试非法输入返回 422 或 400 5. 测试结束后给出运行命令有了自动化测试后续再让 Claude Code 改代码时回归成本会低很多。7. 接口 API 与批量任务自动化农业物联网监测平台做出来后下一步通常是接入更多设备或做定时统计任务。这部分工作可以用 Claude Code 快速扩展。先看一个手动调用接口的示例。假设后端地址是http://127.0.0.1:8000注册设备并写入数据curl -X POST http://127.0.0.1:8000/api/devices \ -H Content-Type: application/json \ -d {name:温室1号,location:A区-1号棚,sensor_types:[temperature,humidity,soil_moisture]}如果你更喜欢用 Python 脚本批量注册设备参考下面的请求模板import requests BASE http://127.0.0.1:8000 def register_device(name: str, location: str, sensor_types: list): resp requests.post( f{BASE}/api/devices, json{name: name, location: location, sensor_types: sensor_types}, timeout10, ) print(resp.status_code, resp.json()) # 批量注册示例 for i in range(1, 6): register_device(f温室{i}号, fA区-{i}号棚, [temperature, humidity])在实际生产中批量任务要考虑失败重试和幂等性。设备注册如果重复提交会创建重复记录所以项目里要加唯一标识或去重逻辑。这一点可以在设计阶段直接要求 Claude Code 实现。再看 Claude Code 自身怎么承担批量自动化任务。它支持非交互模式可以把任务交给脚本或 CI# 让 Claude Code 读取需求文件并生成代码 claude -p 读取 docs/tasks.md 中的任务列表逐项实现并运行测试确认通过 --output-format json比如你有一个 agriculture 的定时日报需求每天统计各设备的平均温度、平均湿度、异常次数然后生成 Markdown 报告。你可以让 Claude Code 生成一个定时脚本再通过 cron 或任务计划程序每天调用。这样平台就从“能看数据”升级为“能自动产出决策信息”。使用非交互模式时建议把任务描述写清楚明确输入和输出文件路径避免 AI 在“哪个目录、生成什么格式”上猜测。如果任务太大拆成多个子任务依次执行稳定性会好很多。8. 资源占用与性能观察性能方面没有一个适用于所有机器的固定数字要结合你的实际环境和配置来观察。农业物联网平台运行时的资源占用主要来自四个环节传感器数据写入、数据库查询、WebSocket 实时推送、前端图表渲染。先看后端。FastAPI 在本地开发时资源占用通常不高但如果数据写入频率很高SQLite 会成为瓶颈。SQLite 适合单机开发和低并发场景如果传感器数量达到几十上百个并且上报间隔很短建议切换到 PostgreSQL这一步可以在项目初期就写进 CLAUDE.md。再看前端。ECharts 实时曲线在数据点很多时会比较消耗 CPU解决思路是前端只保留最近 N 条数据或者后端做聚合。你可以让 Claude Code 生成一个数据聚合接口按分钟或小时粒度返回统计值大幅降低前端渲染压力。观察资源占用的方式很简单本地运行后端和前端后使用系统自带的资源监视器或top命令查看 CPU 和内存。关于 Claude Code 本身值得注意的是上下文消耗。AI Agent 的 token 消耗会随会话长度增长长时间会话后如果发现响应变慢优先使用/compact压缩上下文再继续任务。如果需要压测可以让 Claude Code 生成一个简单的压力测试脚本模拟 100 个设备、每个设备 10 秒上报一次数据。但不要因为是 AI 生成的脚本就让它在生产环境直接跑先在本机验证观察数据库和接口的承受能力。9. Claude Code 与项目常见问题排查这一章列出实际操作中最容易遇到的问题按“现象、原因、排查、解决”的结构整理成表。问题现象可能原因排查方式解决方案npm 安装 Claude Code 失败Node 版本过低 / npm 源不稳定执行node -v查看完整报错升级到 Node 18或切换 npm 源后重试运行claude提示登录或订阅不可用账号权限不足 / API Key 未配置执行claude /status查看认证信息配置ANTHROPIC_API_KEY或联系账号管理员确认权限报错xxx is not a model this version of claude code recognizes模型名拼写错误 / 模型接口不兼容检查环境变量和/model中的模型名修正模型名为支持范围内的值确认第三方接口的模型映射后端依赖安装报错Python 版本和依赖不兼容查看 requirements.txt 中的依赖版本创建专用虚拟环境指定 Python 版本后重新安装前端依赖安装报错Node 版本与 Vite 版本不匹配查看 npm 运行日志使用项目要求的 Node 版本或删除 node_modules 重装后端端口被占用上次启动的进程未退出使用lsof -i:8000或netstat -ano查看杀掉占用进程或修改后端端口配置模拟器连接 MQTT 失败Broker 未启动 / 地址配置错误查看模拟器日志和 MQTT 地址配置启动本机 Broker或改用 HTTP API 模式WebSocket 页面无数据后端未开启推流 / 地址错误打开浏览器开发者工具检查网络连接核对 WebSocket 地址确认后端日志有推送记录AI 生成代码运行后报模块缺失依赖列表不完整查看报错模块名让 Claude Code 补全依赖或手动安装缺失包Claude Code 上下文过长导致生成质量下降单次会话任务过多执行/compact压缩上下文拆分任务新开会话分区处理不同模块列在这里的排查方案是通用处理思路具体到你的环境还是要以实际报错内容为准。遇到问题先看日志不要上来就删文件重装那样往往更浪费时间。10. 最佳实践与使用建议基于农业物联网平台这个案例我总结了 7 条 Claude Code 工程化使用的建议。第一把 CLAUDE.md 当作项目契约。技术栈、目录结构、读写规范、禁止事项都写进去。AI Agent 的上下文是有限的项目规则写清楚它能减少很多无效尝试。第二每个阶段先跑通再进入下一步。骨架、数据模块、可视化、告警四个阶段拆分执行每步都有验证动作。这样排错范围小也方便用 git 回退到可用状态。第三让 AI 生成测试。不仅是业务代码测试代码也交给 Claude Code 写。有了测试后面做代码修改时AI 可以自己跑测试并修复回归问题。第四不要让 AI 直接执行破坏性命令。例如清空数据库、删除目录、覆盖生产配置这类操作要在提示词里明确禁止。开发环境内可以试验但也要先确认分支可回滚。第五敏感配置不进仓库。数据库连接串、API Key、设备密钥统一通过.env管理并在.gitignore中忽略。尤其农业物联网平台可能连接到真实的设备网关密钥泄露后果比普通 Demo 更严重。第六涉及设备控制必须加鉴权。如果平台将来要接自动灌溉、风机、卷帘等执行器后端接口必须做用户认证和操作权限控制并且保留操作日志。这块可以在 CLAUDE.md 里写死强制 AI 生成代码时遵守。第七每完成一个功能就提交一次 git。这样做的好处是AI 改坏代码之后可以快速回滚也让 Claude Code 在判断当前项目状态时有更清晰的边界。11. 总结与下一步这个案例里最值得尝试的点是用自然语言把一个农业物联网监测平台从零到一地搭出来。你可以亲眼看到 Claude Code 如何从项目骨架开始逐步完成数据模型、接口、实时推送、告警和前端可视化整个过程不是一次性生成大量代码而是分阶段产出可运行的模块。建议你先验证最小链路安装 Claude Code初始化一个 FastAPI 和 Vue 的骨架自己跑通健康检查接口。这一步过了再进入传感器数据模拟和实时曲线展示。最容易踩的坑集中在两个地方第一是认证和账号权限问题CLI 工具本身安装不难难的是启动时的权限配置第二是 AI 生成的代码依赖容易不完整运行时报错要找对应模块补齐。从扩展角度看这个平台还可以继续加历史趋势预测、多温区管理、移动端小程序、设备在线离线监测、批量导出日报等能力。你甚至可以把“从 0 到 1 搭农业物联网平台”的方法复制到其他场景比如环境监测、养殖场监控、仓库温湿度管理。本质上Claude Code 省掉的是大量重复的 CRUD 和前后端胶水代码但架构设计、权限控制和数据合规这些事情仍然需要你自己把关。 Claude Code实战：从零搭建农业物联网监测平台
这次我们来看一个具体案例用 Claude Code 搭建一套农业物联网监测平台。Claude Code 是 Anthropic 推出的命令行 AI 编程工具它不只是帮你补全代码而是可以直接在终端里理解需求、读写项目文件、执行命令、跑测试相当于一个能动手改代码的 AI 开发助手。农业物联网这个案例有意思的地方在于它不是一个简单的 CRUD 练习而是把设备接入、数据采集、实时展示、异常告警串成一条完整链路正好能检验 AI 编程 Agent 能不能从零把一个系统搭起来。本文会围绕“Claude Code 100 个案例”这个主线以农业物联网监测平台作为实操目标给出从环境准备、安装启动、分阶段编码、效果验证到接口调用和自动化批量任务的完整流程。我不会只讲概念重点是你照着操作能否跑通以及遇到问题怎么排查。如果你正在关注 Claude Code 怎么落地真实项目或者准备做 IoT 方向的小型平台这篇文章可以直接收藏。1. Claude Code 核心能力速览先把 Claude Code 本身的能力和本次农业物联网案例的定位放在一张表里方便快速判断这个工具适不适合你。能力项说明工具类型命令行 AI 编程 Agent由 Anthropic 推出主要能力理解自然语言需求、读写项目文件、执行终端命令、生成并修改代码、运行测试、管理多文件工程使用方式终端交互模式claude单次任务模式claude 任务描述--print输出结果依赖环境需要 Node.js 18 及以上通过 npm 全局安装认证方式Anthropic 账号登录或配置 API Key具体以你的账号权限为准项目规则通过项目根目录的 CLAUDE.md 约定技术栈、目录结构和编码规范是否支持批量任务支持可用非交互模式接入脚本、CI 或定时任务是否支持 API 调用支持命令行输出 JSON 或纯文本便于程序消费适合场景原型开发、中小型系统搭建、代码重构、测试补充、自动化脚本生成本次案例目标用 Claude Code 搭建农业物联网监测平台覆盖采集、存储、展示、告警四个环节从工具角度看Claude Code 会把“需求 项目规则 当前文件状态”统一放进上下文然后通过工具调用完成文件修改和执行命令。这套机制决定了它适合做多文件工程而不只是单文件的代码生成。农业物联网监测平台恰好是多模块项目适合拿出来当一个完整的 Agent 工作流示范。2. 农业物联网监测平台要解决什么问题农业物联网监测平台的核心需求可以拆成四块传感器数据采集、数据存储与管理、实时可视化监控、异常阈值告警。典型的场景是温室大棚里部署温度、湿度、土壤水分、光照等传感器数据通过 MQTT 或 HTTP 上报到平台平台把这些数据存下来在 Web 页面上展示实时曲线遇到温度过高、土壤过干等异常时触发告警。用 Claude Code 来搭这套系统重点不是让 AI 一次性吐出所有代码而是把它当成一个能持续沟通的工程助理。你可以先让它搭骨架再逐步补充数据模型、采集接口、前端页面和告警规则每一步都能运行验证后再进入下一步。这样做的好处是AI 生成的内容始终处于可运行状态而不是一个看起来很完整却跑不起来的代码堆。这个案例适合谁适合想了解 AI 编程 Agent 如何参与真实项目开发的开发者适合需要快速搭建 IoT 原型在做毕设或内部展示的学生和工程师也适合想验证 Claude Code 是否能替代部分重复编码工作的人。不适合的场景是直接把 AI 生成的代码部署到生产温室控制系统中不做审查这风险太高另外如果涉及真实农场的地理位置、产量、经营数据必须先处理数据合规和访问权限不能为了演示随意采集真实数据。在合规和隐私方面要特别强调本文所有内容都围绕本地开发测试展开不要用公网开放访问你的农业平台。涉及设备控制、自动化灌溉、卷帘电机等执行操作时必须做人工授权和操作审计不能让 AI 生成的接口直接控制实体设备。3. Claude Code 环境准备与前置条件在开始搭建农业物联网平台之前先把 Claude Code 的运行环境准备好。整个链条并不复杂但 Node 版本不对会直接导致安装失败。第一操作系统。Windows、macOS、Linux 都可以跑 Claude Code下面命令在 Windows 上建议通过 PowerShell 或 Git Bash 执行macOS/Linux 直接在终端执行。本文以类 Unix 环境为主Windows 用户只需要把命令中的路径和环境变量写法按系统习惯调整一下。第二Node.js 版本。Claude Code 是 npm 包要求 Node.js 18 及以上。先检查当前版本node -v npm -v如果版本过低建议用 nvm 安装较新的 Node LTS 版本不要把系统自带的 Node 环境弄乱。这一步如果没做对后面安装 Claude Code 会出现各种模块加载错误排查起来很浪费时间。第三IDE 或终端。你可以直接在系统终端里用 Claude Code也可以在 VS Code 的终端里使用。如果你习惯图形界面在 VS Code 中打开项目目录然后调出终端运行claude即可。VS Code 的好处是能实时看到 AI 修改文件的 diff方便 review。第四认证准备。Claude Code 启动后通常需要登录 Anthropic 账号或者通过ANTHROPIC_API_KEY环境变量配置 API Key。团队或组织账号如果禁用了 Claude 订阅访问 Claude Code需要联系管理员确认权限或改用 API Key 方式。# 设置 API Key实际 Key 需要替换为你自己的 export ANTHROPIC_API_KEYsk-你的key如果你使用的是兼容接口或第三方模型网关需要把ANTHROPIC_BASE_URL等环境变量一并配置好并确认模型名和接口格式与当前 Claude Code 版本兼容。4. Claude Code 安装与启动方式Claude Code 的安装很简单npm 全局安装一条命令npm install -g anthropic-ai/claude-code安装完成后确认版本claude --version如果以后需要更新执行claude update启动方式分两种。第一种是交互模式进入项目目录后直接运行claude然后在终端里用自然语言描述需求。第二种是单次任务模式直接传入提示词适合脚本化调用# 交互模式 cd farm-iot claude # 单次任务模式生成 README claude 为当前项目生成一个 README.md包含项目简介和启动方式在交互模式里有一些常用操作需要记住/init可以初始化项目上下文/add-dir可以把目录加入上下文/compact可以压缩过长的上下文/clear清空当前对话/status查看当前状态。如果上下文太长导致生成质量变差优先用/compact不要盲目新开对话。启动后Claude Code 会在项目目录下自动管理工作文件。为了让它更好地理解你的需求我建议在项目根目录创建CLAUDE.md把技术栈和约束写进去。下面是一份农业物联网项目的规则示例# CLAUDE.md ## 项目目标 构建一个农业物联网监测平台覆盖传感器数据采集、存储、可视化与告警。 ## 技术栈 - 后端Python FastAPI - 数据库SQLite开发/ PostgreSQL生产 - 前端Vue 3 Vite ECharts - 传输协议MQTT备选 HTTP API - 认证开发阶段可跳过生产必须接入登录鉴权 ## 项目约束 - 生成的代码必须提供启动方式说明 - 敏感配置统一放 .env不要写入代码 - 设备控制类接口必须添加权限校验CLAUDE.md的作用是让 AI 在每次生成代码时都遵守这些约定。没有这个文件Claude Code 只能靠当前对话的上下文一旦会话变长就容易偏离方向。5. 用 Claude Code 搭建农业物联网平台分阶段实操这一部分是重点。我会把整个搭建过程拆成四个阶段每个阶段都给出提示词示例、预期产物和验证方式。建议你按阶段执行不要一次性让 Claude Code 生成全部代码否则后面排错会非常痛苦。5.1 阶段一初始化项目骨架第一个阶段的目标是跑通一个最小可运行的前后端骨架。不要一上来就加入传感器、数据库、MQTT 等复杂功能。在空目录farm-iot下启动 Claude Code 后输入我们在当前目录搭建农业物联网监测平台。请先初始化项目骨架 1. 后端使用 Python FastAPI提供 /health 健康检查接口 2. 前端使用 Vue 3 Vite首页显示系统状态卡片 3. 开发阶段先不用数据库页面数据用 mock 4. 生成启动说明 README.md 5. 完成后再告诉我如何启动和验证预期产出是一个包含backend和frontend子目录的项目骨架。这里要重点验证两件事后端能否启动并返回健康检查信息前端能否启动并显示页面。不要继续往后做功能先把两个服务跑通。如果 Claude Code 在生成过程中使用了虚拟环境或 npm 安装依赖注意看终端输出是否成功。这一步常见的坑是 Python 版本和 Node 版本不匹配后续我在第九章统一说明排查方法。5.2 阶段二传感器数据采集与设备管理骨架跑通后进入核心业务开发。这个阶段要完成三件事设备管理的数据模型、模拟传感器数据上报、Rest API 接口。继续在 Claude Code 交互中提示在现有骨架上增加物联网数据模块 1. 定义 Device 模型字段包括 id、name、location、sensor_types、status 2. 定义 SensorRecord 模型字段包括 device_id、sensor_type、value、unit、created_at 3. 开发阶段使用 SQLite 存储用 SQLAlchemy 管理 4. 提供设备注册、设备列表、传感器数据写入、传感器数据查询接口 5. 写一个 simulator/sensor_sim.py模拟温湿度数据定时上报 6. 完成后给出接口文档和启动步骤如果这一阶段生成顺利你会看到一个具备基础 CRUD 能力的后端同时有一个模拟传感器数据的脚本。这里建议让 Claude Code 顺便生成一个docs/api.md把接口的作用、参数和返回示例记录下来。这个文档后面无论是自测还是接入前端都非常有用。验证方式先启动后端然后单独运行传感器模拟脚本最后通过接口查询数据。例如# 查询设备列表 curl http://127.0.0.1:8000/api/devices # 查询某个设备最近的温湿度数据 curl http://127.0.0.1:8000/api/devices/1/records?limit20这个阶段最值得检查的是数据模型设计是否合理传感器类型是否可扩展时间字段是否带时区设备状态是否便于后续做在线离线判断。如果发现 AI 生成的数据模型有缺陷直接让它修改不用自己动手。5.3 阶段三实时监测与可视化数据已经能写入接下来把它展示出来。这个阶段引入 WebSocket 和 ECharts。在现有基础上增加实时监测页面 1. 后端增加 WebSocket 接口用于向前端推送最新传感器数据 2. 传感器模拟脚本改为持续上报并支持多个设备 3. 前端增加实时曲线页面用 ECharts 展示温度和湿度变化 4. 如果没有新数据页面不要闪烁保持稳定 5. 完成后说明如何同时启动后端、模拟器和前端进行联调这里建议让 Claude Code 把模拟器改成可以指定设备数量和上报频率方便后续测试实时性。当前端实时曲线能随模拟数据滚动时这个阶段就算通过。联调过程中要注意WebSocket 的地址不能写死端口和路径要和后端配置一致。如果页面里没数据优先查看浏览器开发者工具里的网络请求和 WebSocket 连接状态再回过头看后端日志。5.4 阶段四告警规则与阈值触发最后一个核心功能是告警。农业物联网平台的告警逻辑通常不复杂但对工程化要求比较高。增加告警模块 1. 支持为设备配置告警规则例如当 temperature 大于 35 或 soil_moisture 小于 30 时触发 2. 后端在写入传感器数据时判断规则触发后生成 AlertRecord 3. 提供告警记录查询接口支持按设备、规则、时间范围筛选 4. 模拟器里故意产生一条温度越界数据验证告警能触发 5. 前端告警页面展示最新告警列表和状态这一阶段判断成功的关键是端到端能跑通设备注册、模拟数据写入、规则匹配、告警生成、前端展示。除了正常流程还要检查异常流程比如阈值配置错误时接口是否会返回明确报错避免埋雷。告警模块做完后这个农业物联网监测平台的 MVP 就成立了。如果你还想继续扩展可以让 Claude Code 增加历史数据统计、批量导出 CSV、日报生成等能力这些放在批量任务章节讲。6. 功能测试与效果验证AI 生成的代码如果不做系统性验证很容易出现“看起来对跑起来错”的情况。建议按照下面的测试维度逐项验证。第一基础生成能力测试。分别测试设备注册、数据写入、数据查询三个核心接口确认接口能通返回字段符合预期。第二实时推送测试。启动多个模拟传感器后确认 WebSocket 能持续推送数据前端不再依赖手动刷新。第三告警触发测试。将某个设备的温度阈值调到很低比如 10 度然后让模拟器上报 30 度确认告警记录能被创建并展示。第四批量数据测试。用脚本一次性写入 1000 条传感器数据观察接口响应时间和页面加载是否正常。这个测试不需要很高的并发量重点是确认数据库设计和查询语句没有明显性能问题。第五异常输入测试。提交不存在的设备 ID、空数据、超大数值确认接口能返回清晰的错误信息而不是直接 500。如果你不想手工点接口可以让 Claude Code 生成一套 pytest 测试用例。提示词可以这样写为当前后端项目生成 pytest 测试 1. 测试设备注册、列表、详情接口 2. 测试传感器数据写入和查询 3. 测试告警规则触发逻辑 4. 测试非法输入返回 422 或 400 5. 测试结束后给出运行命令有了自动化测试后续再让 Claude Code 改代码时回归成本会低很多。7. 接口 API 与批量任务自动化农业物联网监测平台做出来后下一步通常是接入更多设备或做定时统计任务。这部分工作可以用 Claude Code 快速扩展。先看一个手动调用接口的示例。假设后端地址是http://127.0.0.1:8000注册设备并写入数据curl -X POST http://127.0.0.1:8000/api/devices \ -H Content-Type: application/json \ -d {name:温室1号,location:A区-1号棚,sensor_types:[temperature,humidity,soil_moisture]}如果你更喜欢用 Python 脚本批量注册设备参考下面的请求模板import requests BASE http://127.0.0.1:8000 def register_device(name: str, location: str, sensor_types: list): resp requests.post( f{BASE}/api/devices, json{name: name, location: location, sensor_types: sensor_types}, timeout10, ) print(resp.status_code, resp.json()) # 批量注册示例 for i in range(1, 6): register_device(f温室{i}号, fA区-{i}号棚, [temperature, humidity])在实际生产中批量任务要考虑失败重试和幂等性。设备注册如果重复提交会创建重复记录所以项目里要加唯一标识或去重逻辑。这一点可以在设计阶段直接要求 Claude Code 实现。再看 Claude Code 自身怎么承担批量自动化任务。它支持非交互模式可以把任务交给脚本或 CI# 让 Claude Code 读取需求文件并生成代码 claude -p 读取 docs/tasks.md 中的任务列表逐项实现并运行测试确认通过 --output-format json比如你有一个 agriculture 的定时日报需求每天统计各设备的平均温度、平均湿度、异常次数然后生成 Markdown 报告。你可以让 Claude Code 生成一个定时脚本再通过 cron 或任务计划程序每天调用。这样平台就从“能看数据”升级为“能自动产出决策信息”。使用非交互模式时建议把任务描述写清楚明确输入和输出文件路径避免 AI 在“哪个目录、生成什么格式”上猜测。如果任务太大拆成多个子任务依次执行稳定性会好很多。8. 资源占用与性能观察性能方面没有一个适用于所有机器的固定数字要结合你的实际环境和配置来观察。农业物联网平台运行时的资源占用主要来自四个环节传感器数据写入、数据库查询、WebSocket 实时推送、前端图表渲染。先看后端。FastAPI 在本地开发时资源占用通常不高但如果数据写入频率很高SQLite 会成为瓶颈。SQLite 适合单机开发和低并发场景如果传感器数量达到几十上百个并且上报间隔很短建议切换到 PostgreSQL这一步可以在项目初期就写进 CLAUDE.md。再看前端。ECharts 实时曲线在数据点很多时会比较消耗 CPU解决思路是前端只保留最近 N 条数据或者后端做聚合。你可以让 Claude Code 生成一个数据聚合接口按分钟或小时粒度返回统计值大幅降低前端渲染压力。观察资源占用的方式很简单本地运行后端和前端后使用系统自带的资源监视器或top命令查看 CPU 和内存。关于 Claude Code 本身值得注意的是上下文消耗。AI Agent 的 token 消耗会随会话长度增长长时间会话后如果发现响应变慢优先使用/compact压缩上下文再继续任务。如果需要压测可以让 Claude Code 生成一个简单的压力测试脚本模拟 100 个设备、每个设备 10 秒上报一次数据。但不要因为是 AI 生成的脚本就让它在生产环境直接跑先在本机验证观察数据库和接口的承受能力。9. Claude Code 与项目常见问题排查这一章列出实际操作中最容易遇到的问题按“现象、原因、排查、解决”的结构整理成表。问题现象可能原因排查方式解决方案npm 安装 Claude Code 失败Node 版本过低 / npm 源不稳定执行node -v查看完整报错升级到 Node 18或切换 npm 源后重试运行claude提示登录或订阅不可用账号权限不足 / API Key 未配置执行claude /status查看认证信息配置ANTHROPIC_API_KEY或联系账号管理员确认权限报错xxx is not a model this version of claude code recognizes模型名拼写错误 / 模型接口不兼容检查环境变量和/model中的模型名修正模型名为支持范围内的值确认第三方接口的模型映射后端依赖安装报错Python 版本和依赖不兼容查看 requirements.txt 中的依赖版本创建专用虚拟环境指定 Python 版本后重新安装前端依赖安装报错Node 版本与 Vite 版本不匹配查看 npm 运行日志使用项目要求的 Node 版本或删除 node_modules 重装后端端口被占用上次启动的进程未退出使用lsof -i:8000或netstat -ano查看杀掉占用进程或修改后端端口配置模拟器连接 MQTT 失败Broker 未启动 / 地址配置错误查看模拟器日志和 MQTT 地址配置启动本机 Broker或改用 HTTP API 模式WebSocket 页面无数据后端未开启推流 / 地址错误打开浏览器开发者工具检查网络连接核对 WebSocket 地址确认后端日志有推送记录AI 生成代码运行后报模块缺失依赖列表不完整查看报错模块名让 Claude Code 补全依赖或手动安装缺失包Claude Code 上下文过长导致生成质量下降单次会话任务过多执行/compact压缩上下文拆分任务新开会话分区处理不同模块列在这里的排查方案是通用处理思路具体到你的环境还是要以实际报错内容为准。遇到问题先看日志不要上来就删文件重装那样往往更浪费时间。10. 最佳实践与使用建议基于农业物联网平台这个案例我总结了 7 条 Claude Code 工程化使用的建议。第一把 CLAUDE.md 当作项目契约。技术栈、目录结构、读写规范、禁止事项都写进去。AI Agent 的上下文是有限的项目规则写清楚它能减少很多无效尝试。第二每个阶段先跑通再进入下一步。骨架、数据模块、可视化、告警四个阶段拆分执行每步都有验证动作。这样排错范围小也方便用 git 回退到可用状态。第三让 AI 生成测试。不仅是业务代码测试代码也交给 Claude Code 写。有了测试后面做代码修改时AI 可以自己跑测试并修复回归问题。第四不要让 AI 直接执行破坏性命令。例如清空数据库、删除目录、覆盖生产配置这类操作要在提示词里明确禁止。开发环境内可以试验但也要先确认分支可回滚。第五敏感配置不进仓库。数据库连接串、API Key、设备密钥统一通过.env管理并在.gitignore中忽略。尤其农业物联网平台可能连接到真实的设备网关密钥泄露后果比普通 Demo 更严重。第六涉及设备控制必须加鉴权。如果平台将来要接自动灌溉、风机、卷帘等执行器后端接口必须做用户认证和操作权限控制并且保留操作日志。这块可以在 CLAUDE.md 里写死强制 AI 生成代码时遵守。第七每完成一个功能就提交一次 git。这样做的好处是AI 改坏代码之后可以快速回滚也让 Claude Code 在判断当前项目状态时有更清晰的边界。11. 总结与下一步这个案例里最值得尝试的点是用自然语言把一个农业物联网监测平台从零到一地搭出来。你可以亲眼看到 Claude Code 如何从项目骨架开始逐步完成数据模型、接口、实时推送、告警和前端可视化整个过程不是一次性生成大量代码而是分阶段产出可运行的模块。建议你先验证最小链路安装 Claude Code初始化一个 FastAPI 和 Vue 的骨架自己跑通健康检查接口。这一步过了再进入传感器数据模拟和实时曲线展示。最容易踩的坑集中在两个地方第一是认证和账号权限问题CLI 工具本身安装不难难的是启动时的权限配置第二是 AI 生成的代码依赖容易不完整运行时报错要找对应模块补齐。从扩展角度看这个平台还可以继续加历史趋势预测、多温区管理、移动端小程序、设备在线离线监测、批量导出日报等能力。你甚至可以把“从 0 到 1 搭农业物联网平台”的方法复制到其他场景比如环境监测、养殖场监控、仓库温湿度管理。本质上Claude Code 省掉的是大量重复的 CRUD 和前后端胶水代码但架构设计、权限控制和数据合规这些事情仍然需要你自己把关。