# 码上手（Hands-on AI Coding）

> 面向中文用户的 AI 编程练习场：系统学习路径、浏览器里的 Claude Code 模拟器、AI 提示词教练、精选 Skill 与 MCP，帮你把 AI 编程真正练会。

每一课和每个模板都提供 Markdown 版本：把页面地址末尾的 `/` 换成 `.md` 即可，例如 /learn/start/ai-coding-map.md。全部课程合集见 /llms-full.txt。

## 起步：第一次让 AI 写出能跑的东西

- [AI 编程是什么：从补全到智能体](https://coding.chengyu.dev/learn/start/ai-coding-map.md): 先建立一张地图。AI 编程工具经历了补全、对话、智能体三个阶段，它们各自擅长什么、你还需要会什么，决定了你该怎么学、从哪里开始。
- [选工具：你的第一个 AI 编程工具](https://coding.chengyu.dev/learn/start/choose-your-tool.md): 市面上的 AI 编程工具名字多到眼花。这一课按「你怎么跟它协作」把它们分成四类，讲清各自的上手难度和费用模式，再按人群给出第一个工具的选法。
- [安装 Claude Code：跑通第一次会话](https://coding.chengyu.dev/learn/start/install-claude-code.md): 从「终端是什么」讲起，带你在 macOS、Windows 或 Linux 上装好 Claude Code、登录账号、完成第一次会话，并附上最常见安装报错的排查思路。
- [第一个项目：用对话做一个番茄钟](https://coding.chengyu.dev/learn/start/first-project.md): 从一个空文件夹开始，用四五轮对话做出能在浏览器里运行的番茄钟网页。你会练到描述需求、审阅计划、提出修改、让智能体自己验证，并学会处理第一次报错。
- [和智能体沟通的 6 个习惯](https://coding.chengyu.dev/learn/start/talk-to-agents.md): 同一个智能体，有人用得顺手，有人天天返工，差别多半在沟通方式。这一课用「差的说法 vs 好的说法」对比，讲清六个能立刻用上的习惯。
- [看懂 AI 改了什么：用 git 管住改动](https://coding.chengyu.dev/learn/start/read-and-verify.md): 智能体改得快，你得看得清、退得回。这一课教你最小够用的 git：状态、差异、提交、回滚，让智能体帮你写提交信息，并搞清 Claude Code 自带的回退和 git 各管什么。

## Claude Code 精通

- [工作原理：看懂 Claude Code](https://coding.chengyu.dev/learn/claude-code/how-it-works.md): 理解智能体循环、内置工具和上下文窗口这三样东西，你就能看懂 Claude Code 每一步在做什么，知道它为什么先读文件，也能挑对终端、IDE、桌面或网页里最适合你的那个入口。
- [CLAUDE.md 与记忆：写好项目说明](https://coding.chengyu.dev/learn/claude-code/claude-md.md): 每次开新会话都要重新交代「用 pnpm、接口统一包装返回值」？这一课讲清 CLAUDE.md 各层级的位置和加载顺序、/init 与 @ 导入的用法、自动记忆的分工，以及怎样写出一份短而有效的项目说明。
- [权限模式与安全：放手但不失控](https://coding.chengyu.dev/learn/claude-code/permissions.md): 确认弹窗点到第二十次，你就开始无脑点「是」了。这一课讲清六种权限模式、allow / ask / deny 规则的写法和 Bash 沙箱，以及怎样按场景在安全与效率之间取舍。
- [管理上下文与会话：让它一直清醒](https://coding.chengyu.dev/learn/claude-code/context.md): 会话越聊越长，Claude 开始忘约定？这一课教你看清和清理上下文，用 --continue、--resume 恢复会话，用检查点回退，并判断何时该开新会话、何时交给子智能体。
- [Skill：把重复流程变成一条命令](https://coding.chengyu.dev/learn/claude-code/skills.md): 每次发版都要粘贴同一段检查清单？这一课讲清 SKILL.md 的结构、存放位置、前置信息字段和按需加载原理，分清 Skill、CLAUDE.md 与斜杠命令各管什么，并手把手写一个生成中文发版说明的 Skill。
- [MCP：给 Claude Code 接上外部工具](https://coding.chengyu.dev/learn/claude-code/mcp.md): 学会用 claude mcp add 接入浏览器、GitHub、数据库、文档检索等 MCP 服务器，分清 local、project、user 三种作用域和 .mcp.json，并知道接入第三方服务器时要守住哪些安全底线。
- [Hooks：把规矩写成必然发生的动作](https://coding.chengyu.dev/learn/claude-code/hooks.md): CLAUDE.md 里的要求 Claude 偶尔会忘，Hooks 不会。学会在生命周期事件上挂脚本，用 matcher 精确触发，用退出码和 JSON 控制结果，做出自动格式化、高危命令拦截和完成通知三个实用 Hook。
- [子智能体与并行：一个人带一支队伍](https://coding.chengyu.dev/learn/claude-code/subagents-parallel.md): 用子智能体把查资料、跑测试这类「脏活」隔离在独立上下文里，用 .claude/agents/ 定义可复用的专家，再用 git worktree、后台会话和 agent view 让多个 Claude 同时干活又互不踩脚。
- [无头模式与 CI：让 Claude 在流水线里干活](https://coding.chengyu.dev/learn/claude-code/headless-ci.md): 不开交互界面，用 claude -p 把 Claude Code 当成一个命令行工具嵌进脚本和 CI；掌握输出格式、权限与 --bare，接入 GitHub Actions 自动评审 PR，并了解什么时候该换成 Agent SDK。

## 实战：从想法到上线一个网站

- [从想法到规格：让 AI 先追问你](https://coding.chengyu.dev/learn/ship/idea-to-spec.md): 贯穿项目第一步。用 Claude Code 的访谈式提问，把「做一个个人书单网站」这句话变成一页纸规格：用户、场景、页面、数据、验收标准和不做什么。
- [选技术栈并搭骨架：第一次提交](https://coding.chengyu.dev/learn/ship/scaffold.md): 为书单项目选定 Astro、Tailwind 和 Cloudflare Workers，让 Claude Code 初始化项目、写好 CLAUDE.md、完成第一次 git 提交并推到 GitHub。
- [做界面：令牌、组件与截图自查](https://coding.chengyu.dev/learn/ship/build-ui.md): 先定设计令牌再写组件，用假数据做出响应式、支持暗色模式的书单界面，让 Claude Code 自己截图检查，并避开千篇一律的 AI 味审美。
- [加后端：Workers、D1 与 AI](https://coding.chengyu.dev/learn/ship/backend.md): 用 wrangler 配置 D1 数据库和 AI 绑定，写迁移和 API，让每本书保存后自动生成摘要与标签，并用 wrangler secret 管理管理令牌，而不是写进代码。
- [测试与评审：让另一双眼睛挑错](https://coding.chengyu.dev/learn/ship/test-review.md): 把规格里的验收标准变成 Vitest 单元测试和 Playwright 端到端测试，在真实浏览器里验证行为，再让独立会话或子智能体做代码评审与安全检查。
- [上线：域名、自动部署、回滚与监控](https://coding.chengyu.dev/learn/ship/deploy.md): 用 wrangler 完成首次部署，绑定自定义域名，用 GitHub Actions 实现推送即部署并给 API Token 最小权限，再备好检查清单、回滚方案与基础监控。

## AI 编程的工程方法

- [上下文工程：让模型看对东西](https://coding.chengyu.dev/learn/engineering/context-engineering.md): 智能体的表现取决于它每一步读到了什么。本课讲清上下文里装了什么、为什么越长越差，以及压缩、即时检索、外部记忆、子智能体四种手段各自适合什么场景，最后落到项目说明文件该怎么写。
- [规格驱动与计划先行](https://coding.chengyu.dev/learn/engineering/spec-driven.md): 让智能体直接动手，错了的代价是一份一千行的 diff；先把规格和计划写下来，错了的代价是改几行文字。本课讲探索、计划、实现、提交四步工作流，规格怎么写，大任务怎么拆成可验证的小步，以及什么时候别计划。
- [验证闭环：让智能体自己证明做对了](https://coding.chengyu.dev/learn/engineering/verification.md): 智能体说「完成了」不等于完成了。本课讲怎样建立验证闭环：类型与 lint、测试先行、真实运行与浏览器截图、对照验收标准自检、独立复核，以及如何防止智能体靠改测试、写死答案来「骗过」检查。
- [安全：提示注入、密钥与供应链](https://coding.chengyu.dev/learn/engineering/security.md): 智能体会读网页、issue、依赖文档，还能跑命令。本课讲提示注入怎么发生、为什么不能靠提示词防住、怎样用沙箱和权限把风险变成硬边界，并覆盖密钥、幻觉依赖包、MCP 与第三方 Skill 的审查要点。
- [成本与模型选择：把 token 花在刀刃上](https://coding.chengyu.dev/learn/engineering/cost-models.md): 智能体每一步都会把整段上下文重发一遍，账单因此增长得比直觉快。本课讲 token 怎么计费、提示缓存怎么省钱又怎么被破坏、大小模型怎么分工、子智能体能否省钱，以及怎么查看和控制用量。
- [让代码库对智能体友好](https://coding.chengyu.dev/learn/engineering/codebase-ready.md): 智能体的上限，往往由代码库的可读性和反馈速度决定。本课讲一键可跑的脚本、小而快的反馈回路、类型系统、目录与命名、文档就近、AGENTS.md 与 CLAUDE.md 的分工，以及如何用「新员工测试」量化你的代码库。
- [团队落地：配置、评审与度量](https://coding.chengyu.dev/learn/engineering/team-adoption.md): 一个人用得好不等于一个团队用得好。本课讲共享配置怎么进仓库、AI 生成代码的评审规范与责任归属、哪些度量指标有意义而哪些会误导、新人培训路径，以及推广中最常见的反模式。

## 模板库

- [跨工具通用的 AGENTS.md](https://coding.chengyu.dev/recipes/agents-md-cross-tool.md): 用一份 AGENTS.md 同时服务多个编码智能体，并说明 Claude Code 何时直接读取它、何时需要 CLAUDE.md 里的 @AGENTS.md 引用或软链接。
- [前端项目 CLAUDE.md 模板](https://coding.chengyu.dev/recipes/claude-md-frontend.md): 面向 React、Next.js、Astro 等前端项目的 CLAUDE.md，包含常用命令、组件约定、可访问性与输入法细节，以及按文件类型拆分规则的写法。
- [Python 数据与后端项目 CLAUDE.md 模板](https://coding.chengyu.dev/recipes/claude-md-python.md): 适合 FastAPI、数据分析或脚本类 Python 项目的 CLAUDE.md，写清运行命令、分层约定、数据处理红线和数据库迁移规则，减少智能体乱改数据。
- [通用 CLAUDE.md 骨架](https://coding.chengyu.dev/recipes/claude-md-starter.md): 一份适用于任何项目的 CLAUDE.md 起步骨架，涵盖命令、目录、约定、禁区和已知坑，复制后替换占位符即可，建议控制在 200 行以内。
- [个人全局偏好 ~/.claude/CLAUDE.md](https://coding.chengyu.dev/recipes/claude-md-user-global.md): 把语言、沟通风格、安全边界和 Git 习惯写进用户级 CLAUDE.md，让 Claude Code 在所有项目里都按你的方式工作，附 language 设置的补充用法。
- [Hooks：编辑后自动格式化](https://coding.chengyu.dev/recipes/config-hook-auto-format.md): 用 PostToolUse hook 在 Claude 每次编辑或写入文件后自动运行 Prettier 或 ruff，保证格式稳定，附可处理空格路径与多语言的脚本版本。
- [.mcp.json 项目级 MCP 配置示例](https://coding.chengyu.dev/recipes/config-mcp-project.md): 用项目根目录的 .mcp.json 为团队共享 MCP 服务器，示例包含远程 HTTP、带令牌的请求头和本地 stdio 数据库，并说明环境变量、审批与优先级。
- [settings.json 权限白名单示例](https://coding.chengyu.dev/recipes/config-settings-permissions.md): 一份项目级 .claude/settings.json 示例，用 allow、ask、deny 三类规则减少权限弹窗，同时挡住密钥文件读取，并解释规则顺序与路径写法的坑。
- [提示词：需求澄清与写规格](https://coding.chengyu.dev/recipes/prompt-clarify-spec.md): 让智能体先采访你、再把模糊想法整理成带验收标准的 SPEC.md，适用于动手前还没想清楚的中大型功能，避免做到一半发现方向错了。
- [提示词：代码评审](https://coding.chengyu.dev/recipes/prompt-code-review.md): 让智能体以评审者而非作者的身份审阅 diff，只报告影响正确性、安全和需求的问题，并附证据与复现场景，减少无意义的风格挑刺。
- [提示词：陌生代码库导览](https://coding.chengyu.dev/recipes/prompt-codebase-tour.md): 刚接手陌生项目时，让智能体按固定顺序读代码，并产出带文件位置的导览文档，帮你在一小时内搞清结构、主流程、测试方式和风险区。
- [提示词：生成提交信息与 PR 描述](https://coding.chengyu.dev/recipes/prompt-commit-and-pr.md): 让智能体根据暂存区 diff 和近期提交风格写提交信息，再生成包含背景、改动、测试与风险的 PR 描述，写清楚没验证到的内容，不夸大。
- [提示词：排查 bug（复现、定位、修复、验证）](https://coding.chengyu.dev/recipes/prompt-debug-bug.md): 把排查拆成复现、定位、修复、验证四步，要求先写出会失败的测试再动手，并限制猜测次数，避免智能体靠压制报错来交差。
- [提示词：安全重构](https://coding.chengyu.dev/recipes/prompt-safe-refactor.md): 重构前先用测试钉住现有行为，再分小步修改，每一步都运行测试并单独提交，让智能体在不改变外部行为的前提下整理结构，随时可回退。
- [提示词：把截图还原成页面](https://coding.chengyu.dev/recipes/prompt-screenshot-to-page.md): 提供设计稿或网页截图，让智能体先拆解结构再实现，并通过截图对比逐项修正差异，适合快速还原落地页、卡片和后台界面。
- [提示词：为现有代码补测试](https://coding.chengyu.dev/recipes/prompt-write-tests.md): 先让智能体读懂现有测试风格和未覆盖的分支，再按边界、异常、回归三类补测试，并用故意改坏代码的方式确认新测试真的有用。
- [Skill 示例：发布说明生成](https://coding.chengyu.dev/recipes/skill-release-notes.md): 一个完整的 SKILL.md 示例，读取上个版本以来的 git 提交，按用户视角生成发布说明，含目录结构、frontmatter 字段、参数与动态命令用法。
- [工作流：探索、计划、实现、提交](https://coding.chengyu.dev/recipes/workflow-explore-plan-implement-commit.md): 官方推荐的四阶段开发流程，用计划模式把读代码和改代码分开，配套每一阶段可直接发送的提示词，适合改动涉及多个文件或不熟悉的代码时使用。
- [工作流：用 git worktree 并行开发](https://coding.chengyu.dev/recipes/workflow-git-worktree-parallel.md): 用 claude --worktree 为每个任务创建独立检出和分支，让多个会话同时开发互不覆盖，并说明依赖安装、环境文件、清理和基线分支的注意点。
- [工作流：测试驱动的智能体开发](https://coding.chengyu.dev/recipes/workflow-tdd-agent.md): 先写失败测试、再提交测试、再让智能体实现并让它不得修改测试，最后由独立会话评审，用可执行的检查替代人盯人，适合需求明确的功能。

## 目录与数据

- [智能体对比](https://coding.chengyu.dev/agents/)
- [Skill 目录](https://coding.chengyu.dev/skills/)：索引 JSON 在 https://coding.chengyu.dev/skills/index.json
- [MCP 目录](https://coding.chengyu.dev/mcp/)：索引 JSON 在 https://coding.chengyu.dev/mcp/index.json