claude-quickstarts 自主编码 Agent 首次运行看似卡住hang是什么原因【免费下载链接】claude-quickstartsA collection of projects designed to help developers quickly get started with building deployable applications using the Claude API项目地址: https://gitcode.com/GitHub_Trending/an/claude-quickstarts在 claude-quickstarts 仓库里运行 Autonomous Coding Agent 示例autonomous-coding/时如果启动后终端长时间没有新的输出很容易误以为进程已经卡死。autonomous-coding/README.md 在 Troubleshooting 一节中把这一现象列为已知问题结论是这种卡住属于正常行为因为第一个会话正在让 Initializer agent 写出 200 条详细测试用例。本文说明这个现象的成因、如何确认 Agent 确实在工作以及按需缩短首次运行等待时间的方法。hang的成因首个会话在写 feature_list.json这个示例采用双 Agent 模式第一个会话运行 Initializer agent之后的会话运行 Coding agent。prompts/initializer_prompt.md 要求 Initializer 的CRITICAL FIRST TASK是基于app_spec.txt创建feature_list.json其中包含至少 200 条端到端测试用例且至少 25 条测试必须各有 10 步以上。把这份用例清单完整写出来占用了首个会话的大部分时间。README 对此给出的时长预期是首个会话initialization生成feature_list.json需要若干分钟several minutesmay appear to hang - this is normal之后的每个编码迭代可能需要 5-15 分钟视复杂度而定构建全部 200 个 feature 通常需要多个会话、总计数小时many hours。判断是否为首次运行脚本的依据是项目目录里是否存在feature_list.json。如果不存在agent.py 会在启动时打印这样一段提示NOTE: First session takes 10-20 minutes! The agent is generating 200 detailed test cases. This may appear to hang - its working. Watch for [Tool: ...] output.注意脚本横幅写的是 10-20 minutes而 README 写的是 several minutes两处都是文档原文都以首次会话为对象可把两者放在一起作为等待时长的参考区间。如何确认是在正常工作而不是真的卡死文档给出的判断方法只有一个观察终端里的[Tool: ...]输出。README Troubleshooting 一节的原话是 Watch for[Tool: ...]output to confirm the agent is working.agent.py 的实现与这句话对应agent 每调用一次工具终端就打印一行[Tool: 工具名]工具名取自 client.py 中的内置工具列表Read、Write、Edit、Glob、Grep、Bash及 Puppeteer MCP 工具随后打印Input:内容输入超过 200 字符时只展示前 200 个字符并以...结尾工具返回后再打印三态之一[Done]该工具调用成功[Error] ...调用出错展示错误内容的前 500 字符[BLOCKED] ...命令被安全 hook 拦截。所以只要[Tool: ...]行还在持续出现就说明 Agent 仍在干活。另外每个会话结束后脚本会打印进度摘要feature_list.json尚未生成时显示Progress: feature_list.json not yet created生成后变为Progress: 通过数/总数 (百分比)。feature_list.json出现在项目目录里即代表首个会话完成了最耗时的步骤后续会话会基于该文件逐个实现 feature 并把passes标记为true。复现前提与运行命令如果还没有跑过先按 README 的 Prerequisites 完成安装要求 Claude Code CLI 为最新版本# Install Claude Code CLI (latest version required) npm install -g anthropic-ai/claude-code # Install Python dependencies pip install -r requirements.txt验证安装claude --version # Should be latest version pip show claude-code-sdk # Check SDK is installedPython 依赖来自 requirements.txt即claude-code-sdk0.0.25。然后设置 API keyyour-api-key-here替换为你自己的 keyexport ANTHROPIC_API_KEYyour-api-key-here在autonomous-coding/目录下运行示例python autonomous_agent_demo.py --project-dir ./my_project几个影响执行的细节均来自 autonomous_agent_demo.py 与 README相对路径的--project-dir会自动放到generations/目录下默认值为./autonomous_demo_project--model默认使用claude-sonnet-4-5-20250929若ANTHROPIC_API_KEY未设置脚本会打印错误信息并直接退出不会进入会话按CtrlC可以暂停脚本打印 Interrupted by user再运行同一条命令即恢复。恢复后的走向由feature_list.json是否存在决定文件已存在则按续跑处理并使用 Coding agent 的 prompt否则重新走 Initializer 流程。可选缩短首次运行的等待README 的 Tip 给出了两个加快演示的办法减少 feature 数量编辑 prompts/initializer_prompt.md把其中 200 features 的要求改成更小的数字README 举例 20-50首次会话要写出的用例就变少了。限制迭代次数用于测试python autonomous_agent_demo.py --project-dir ./my_project --max-iterations 3--max-iterations默认无限制它限制的是 Agent 迭代会话的总数达到上限后脚本打印Reached max iterations (3)并退出继续运行需去掉该参数再执行。它不会减少首个会话写测试用例清单本身所花的时间。不是正常 hang时的另外两种现象README Troubleshooting 一节还列了两种与正常 hang不同的现象遇到时按文档说明处理Command blocked by security hookAgent 尝试运行不在允许列表中的命令这是安全系统按设计工作终端中对应[BLOCKED] ...输出。确有需要时修改 security.py把该命令加入ALLOWED_COMMANDS。API key not set确认已在 shell 环境中export ANTHROPIC_API_KEY未设置时脚本会在启动阶段直接报错退出。首次会话结束后项目目录中会生成feature_list.json、init.sh、claude-progress.txt、.claude_settings.json等文件见 README 的 Generated Project Structure。判断标准可以收拢为一句话终端有[Tool: ...]行持续输出时等待就是文档预期的正常行为出现[BLOCKED]或 API key 报错则按上面两条对照处理。【免费下载链接】claude-quickstartsA collection of projects designed to help developers quickly get started with building deployable applications using the Claude API项目地址: https://gitcode.com/GitHub_Trending/an/claude-quickstarts创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考