Claude Code 前30分钟检查清单：新手安全上手流程

前30分钟的目标不是大改代码，而是建立可信流程

很多人第一次用 Claude Code 时会直接说“帮我把这个功能做完”或“把项目整理一下”。问题不在于 Claude Code 不能处理复杂任务，而在于新手还没有给它明确边界：哪些文件可以动，哪些命令可以跑，成功标准是什么，结束时要留下什么证据。边界不清楚，30分钟后就容易得到一堆看似合理、但很难审查的改动。

官方Claude Code 概览说明，它可以读取代码库、编辑文件、运行命令，并和开发工具集成。能力越强，第一轮越应该保守。前30分钟最好的结果，是一张项目地图、一个小而可验证的成果、一份验证记录，以及下一步最小任务。

这篇清单可以和 First Task Runbook、Repo Map First Pass、Session Handoff Template 以及 Verification Receipt Workflow 一起使用。先学会这一轮，再扩大到功能开发、测试补齐和团队流程。

新手先理解这几个词

“代码库”就是项目文件夹，里面通常有源代码、测试、配置、脚本和文档。“agent”可以理解为会调查、编辑、执行命令并汇报结果的执行助手。“权限”是安全边界，决定 Claude Code 可以读什么、改什么、运行什么。官方permissions 文档解释了 allow、ask、deny 规则，以及不同权限模式的使用场景。

CLAUDE.md 是项目说明书。你可以把编码规范、架构决策、禁止事项、构建命令和检查清单写进去，让 Claude Code 每次开始时都能读到。官方memory 文档适合理解项目指令和记忆如何帮助后续会话。

“验证”不是一句“应该好了”。验证是可重复的证据，比如 npm run build 通过、测试从红变绿、页面截图、日志检查，或明确写出还没有验证的内容。新手最容易跳过验证，所以第一轮必须先约定验证命令。

30分钟后应该留下什么

成果	内容	价值
项目地图	入口文件、关键目录、常用命令、风险区域	不在不了解结构时乱改
小成果	一个诊断、一个链接修正、一个测试解释或一个复现记录	差异小，容易审查
验证记录	执行的命令、结果、失败点、未确认点	别人能重复检查
下一步	下次最小可执行任务	第二轮更快开始

第一轮不追求“多写代码”。你要训练的是一种节奏：先理解，再缩小范围，再修改，最后验证和交接。

0到5分钟：先要上下文，不要马上实现

把第一条请求写成只读调查。这样可以观察 Claude Code 是否真的理解项目，而不是直接开始猜测。

Read this repository and tell me:
1. the main entry points
2. the commands I will probably need
3. the risky directories I should avoid first
4. the safest high-value first task for a 30-minute session

Do not edit files yet. Give me a short plan and the proof command you would run.

这个提示词会让它同时给出入口、命令、风险目录和一个合理的小任务。官方common workflows也强调先探索、再计划、再实现和验证。前5分钟的价值，是确认它是否知道项目边界。

5到20分钟：选择一个上手场景

第一个场景是解释失败测试。不要先要求修复，而是要求它说明哪个测试失败、输入是什么、期望值是什么、实际值是什么、可能关联哪个文件。只要失败原因被讲清楚，这一轮就有价值。

第二个场景是小范围内容或 CTA 更新。比如确认按钮文案是否清楚，产品页链接是否仍指向 /products/，咨询链接是否仍指向 /training/。这类任务差异小，但对商业页面很重要。

第三个场景是把模糊 bug 变成复现记录。“页面偶尔崩溃”不是好任务。好的第一轮会整理环境、操作步骤、期望结果、实际结果、日志和候选文件。下一轮再修复会更稳。

第四个场景是写一个最小版 CLAUDE.md。不需要一次写完团队手册，只要列出禁止命令、构建命令、测试命令、代码风格和审查证据。需要共享配置时，再参考官方settings 文档。

可直接复制运行的脚本

macOS、Linux 或 WSL 可以在仓库根目录运行这个脚本。它只读取状态，不修改文件。

#!/usr/bin/env bash
set -euo pipefail

echo "== location =="
pwd

echo "== git status =="
git status --short

echo "== package scripts =="
if [ -f package.json ]; then
  node -e "const p=require('./package.json'); console.log(p.scripts || {})"
else
  echo "package.json not found"
fi

echo "== likely docs =="
find . -maxdepth 2 \( -name 'README*' -o -name 'CLAUDE.md' -o -name 'AGENTS.md' \) -print

echo "== recent changed files =="
git diff --name-only

Windows PowerShell 用户可以用这一版。

$ErrorActionPreference = "Stop"

Write-Host "== location =="
Get-Location

Write-Host "== git status =="
git status --short

Write-Host "== package scripts =="
if (Test-Path package.json) {
  node -e "const p=require('./package.json'); console.log(p.scripts || {})"
} else {
  Write-Host "package.json not found"
}

Write-Host "== likely docs =="
Get-ChildItem -Force -File -Include README*,CLAUDE.md,AGENTS.md -Recurse -Depth 2 |
  Select-Object -ExpandProperty FullName

Write-Host "== recent changed files =="
git diff --name-only

交接记录也可以固定格式。保存为 first-30-handoff.mjs 后运行 node first-30-handoff.mjs。

const handoff = {
  outcome: "Adjusted one CTA sentence and confirmed the product/training links stayed visible.",
  verified: ["git status --short", "npm run build"],
  notVerified: ["Mobile visual check"],
  nextStep: "Open the page locally and inspect the CTA area at 390px width.",
};

for (const [label, value] of Object.entries(handoff)) {
  const body = Array.isArray(value) ? value.map((item) => `- ${item}`).join("\n") : value;
  console.log(`## ${label}\n${body}\n`);
}

权限模板可以从保守配置开始。下面是合法 JSON，实际命令请按项目调整。

{
  "permissions": {
    "allow": [
      "Bash(git status *)",
      "Bash(npm run build)",
      "Bash(npm test *)"
    ],
    "deny": [
      "Bash(git push *)",
      "Read(./.env)",
      "Read(./.env.*)"
    ]
  }
}

具体失败案例

失败案例一是让 Claude Code “全部修好”。这个说法没有范围，也没有成功标准。改成“解释一个失败测试”或“只更新一个 CTA 区块并验证链接”会安全很多。

失败案例二是在普通工作目录里使用过强权限。强权限模式适合隔离环境，不适合作为新手默认设置。包含密钥、客户数据或内部资料的项目，应先阅读官方security 文档，并把 .env 等文件加入拒绝规则。

失败案例三是不跑验证命令。看起来合理的解释不等于验证。开始前就要写清楚：这次通过 npm run build、测试、JSON 解析、截图，还是人工页面检查来证明。

失败案例四是不写交接记录。没有记录，第二轮会重复同样的探索。至少留下改了什么、验证了什么、还没验证什么、下一步做什么。

失败案例五是第一轮就追求“自动赚钱”。收益导线很重要，但新手前30分钟应该先确认页面、链接、权限和验证流程可信。流程稳定后，再把 CTA、商品页、咨询页和广告位置作为小任务逐步优化。

下一步和转化路径

个人练习可以先用免费速查表固定常用提示词和检查命令。想要可复用的提示词、CLAUDE.md 模板和审查清单，可以看 ClaudeCodeLab products。如果团队要设计权限、hooks、验证记录和导入培训，请从 Claude Code training and consultation 开始。

在真实仓库试过后，最有用的并不是某个脚本，而是“先画项目地图，最后检查 git status --short”这个习惯。第一轮任务越小，差异越容易信任，第二次 Claude Code 会话也越容易接上。