企业官网建设流程全解析

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 minutes），"may 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 - it's 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 installed

Python 依赖来自 requirements.txt，即claude-code-sdk>=0.0.25。然后设置 API key（your-api-key-here替换为你自己的 key）：

export ANTHROPIC_API_KEY='your-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未设置，脚本会打印错误信息并直接退出，不会进入会话；
• 按Ctrl+C可以暂停，脚本打印 "Interrupted by user"；再运行同一条命令即恢复。恢复后的走向由feature_list.json是否存在决定：文件已存在则按续跑处理并使用 Coding agent 的 prompt，否则重新走 Initializer 流程。

可选：缩短首次运行的等待

README 的 Tip 给出了两个加快演示的办法：

1. 减少 feature 数量：编辑 prompts/initializer_prompt.md，把其中 "200 features" 的要求改成更小的数字（README 举例 20-50），首次会话要写出的用例就变少了。
2. 限制迭代次数（用于测试）：

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 hook"：Agent 尝试运行不在允许列表中的命令，这是安全系统按设计工作（终端中对应[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