在需要为 Claude Code 插件实现按项目…

当要让 Claude Code 插件保存每项目配置或状态，并让 hooks、commands、agents 按配置调整行为时适用。

适用场景

解决思路

1. 在项目根目录的 `.claude/` 下创建 `plugin-name.local.md`，文件名中的 plugin-name 与插件名精确匹配，并使用 `.local.md` 后缀表示用户本地文件。
2. 文件结构使用 YAML frontmatter（开头和结尾的 `---` 之间）存放结构化配置，frontmatter 之后接 markdown 正文存放提示、附加上下文、任务描述、说明或笔记。
3. 使用基础模板：frontmatter 中写 `enabled: true`、`setting1: value1`、`setting2: value2`、`numeric_setting: 42`、`list_setting: ["item1", "item2"]`，正文写 Additional Context、Task descriptions、Additional instructions、Prompts to feed back to Claude、Documentation or notes。
4. 创建示例状态文件 `.claude/my-plugin.local.md`：frontmatter 写 `enabled: true`、`strict_mode: false`、`max_retries: 3`、`notification_level: info`、`coordinator_session: team-leader`，正文写配置说明并注明联系 @team-lead。
5. 从 hooks（Bash 脚本）读取设置：定义 `STATE_FILE=".claude/my-plugin.local.md"`；用 `if [[ ! -f "$STATE_FILE" ]]; then exit 0; fi` 在文件不存在时快速退出。
6. 从 hooks 解析 frontmatter：用 `FRONTMATTER=$(sed -n '/^---$/,/^---$/{ /^---$/d; p; }' "$STATE_FILE")` 提取 `---` 之间的内容。
7. 从 hooks 提取字段并判断：用 `ENABLED=$(echo "$FRONTMATTER" | grep '^enabled:' | sed 's/enabled: *//' | sed 's/^"\(.*\)"$/\1/')` 和 `STRICT_MODE=$(echo "$FRONTMATTER" | grep '^strict_mode:' | sed 's/strict_mode: *//' | sed 's/^"\(.*\)"$/\1/')`；若 `if [[ "$ENABLED" != "true" ]]` 则 `exit 0`；若 `STRICT_MODE` 为 true 则应用严格验证。
8. 从 commands 读取：在命令 markdown 中检查 `.claude/my-plugin.local.md` 是否存在；用 Read tool 读取；解析 YAML frontmatter 提取设置；将设置应用到处理逻辑；按配置行为执行。
9. 从 agents 读取：在 agent 指令中检查 `.claude/my-plugin.local.md`；若存在则解析 YAML frontmatter；根据 enabled、mode 及其他配置字段调整行为。
10. 提取 frontmatter：用 `FRONTMATTER=$(sed -n '/^---$/,/^---$/{ /^---$/d; p; }' "$FILE")` 提取 `---` 之间的全部内容。
11. 读取字符串字段：用 `VALUE=$(echo "$FRONTMATTER" | grep '^field_name:' | sed 's/field_name: *//' | sed 's/^"\(.*\)"$/\1/')`。
12. 读取布尔字段：用 `ENABLED=$(echo "$FRONTMATTER" | grep '^enabled:' | sed 's/enabled: *//')`，然后比较 `if [[ "$ENABLED" == "true" ]]; then`。
13. 读取数字字段：用 `MAX=$(echo "$FRONTMATTER" | grep '^max_value:' | sed 's/max_value: *//')`，然后用 `if [[ $MAX -gt 100 ]]; then` 进行数值比较。
14. 读取 markdown 正文：用 `BODY=$(awk '/^---$/{i++; next} i>=2' "$FILE")` 提取第二个 `---` 之后的内容。
15. 模式 1（临时启用 hooks）：在 hook 脚本中设置 `STATE_FILE=".claude/security-scan.local.md"`；若文件不存在则 `exit 0`；提取 frontmatter 并读取 `enabled`；若 `enabled` 不是 true 则 `exit 0`；然后运行 hook 逻辑。
16. 模式 2（agent 状态管理）：在 `.claude/multi-agent-swarm.local.md` 中设置 `agent_name`、`task_number`、`pr_number`、`coordinator_session`、`enabled`、`dependencies` 等字段；正文写任务分配、成功标准（如 Authentication endpoints created、Tests passing、PR created and CI green）。
17. 模式 2 的 hook 协调：解析 `AGENT_NAME=$(echo "$FRONTMATTER" | grep '^agent_name:' | sed 's/agent_name: *//')` 和 `COORDINATOR=$(echo "$FRONTMATTER" | grep '^coordinator_session:' | sed 's/coordinator_session: *//')`，再用 `tmux send-keys -t "$COORDINATOR" "Agent $AGENT_NAME completed task" Enter` 发送通知。
18. 模式 3（配置驱动行为）：在 `.claude/my-plugin.local.md` 中设置 `validation_level: strict`、`max_file_size: 1000000`、`allowed_extensions: [".js", ".ts", ".tsx"]`、`enable_logging: true`，正文写 Validation Configuration 与策略说明。
19. 模式 3 的使用：读取 `LEVEL=$(echo "$FRONTMATTER" | grep '^validation_level:' | sed 's/validation_level: *//')`，再用 `case "$LEVEL" in strict) ... standard) ... lenient) ... esac` 应用不同验证逻辑。
20. 从 commands 创建设置文件：命令步骤为询问用户配置偏好；创建 `.claude/my-plugin.local.md` 并写入 YAML frontmatter；根据用户输入设置值；告知用户设置已保存；提醒重启 Claude Code 使 hooks 识别变更。
21. 模板生成：在插件 README 中提供 `.claude/my-plugin.local.md` 模板，frontmatter 包含 `enabled`、`mode`、`max_retries` 等，正文写 Plugin Configuration；说明创建或编辑后重启 Claude Code 生效。
22. 文件命名最佳实践：使用 `.claude/plugin-name.local.md` 格式；与插件名精确匹配；使用 `.local.md` 后缀；不要用其他目录、不要命名不一致、不要用不带 `.local` 的 `.md`（可能被提交）。
23. Gitignore：在 `.gitignore` 中添加 `.claude/*.local.md` 和 `.claude/*.local.json`，并在插件 README 中记录。
24. 默认值：当设置文件不存在时提供合理默认值，例如 `if [[ ! -f "$STATE_FILE" ]]; then ENABLED=true; MODE=standard; else ... fi`。
25. 验证：读取 `MAX=$(echo "$FRONTMATTER" | grep '^max_value:' | sed 's/max_value: *//')` 后，用 `if ! [[ "$MAX" =~ ^[0-9]+$ ]] || [[ $MAX -lt 1 ]] || [[ $MAX -gt 100 ]]; then echo "⚠️ Invalid max_value in settings (must be 1-100)" >&2; MAX=10; fi` 验证数值范围并回退默认值。
26. 重启要求：在 README 中说明修改 `.claude/my-plugin.local.md` 后需保存文件、退出 Claude Code、运行 `claude` 或 `cc` 重启、新设置才会加载；hooks 不能在会话内热插拔。
27. 安全-清理用户输入：从用户输入写设置文件时，用 `SAFE_VALUE=$(echo "$USER_INPUT" | sed 's/"/\\"/g')` 转义引号，再用 `cat > "$STATE_FILE" <<EOF` 写入 `user_setting: "$SAFE_VALUE"`。
28. 安全-验证文件路径：若设置包含文件路径，读取 `FILE_PATH=$(echo "$FRONTMATTER" | grep '^data_file:' | sed 's/data_file: *//')`，再用 `if [[ "$FILE_PATH" == *".."* ]]; then echo "⚠️ Invalid path in settings (path traversal)" >&2; exit 2; fi` 检查路径穿越。
29. 安全-权限：设置文件应仅用户可读（`chmod 600`）、不提交到 git、不在用户间共享。
30. 实际示例 multi-agent-swarm：`.claude/multi-agent-swarm.local.md` 中设置 `agent_name: auth-implementation`、`task_number: 3.5`、`pr_number: 1234`、`coordinator_session: team-leader`、`enabled: true`、`dependencies: ["Task 3.4"]`、`additional_instructions: Use JWT tokens, not sessions`；正文写 Task: Implement Authentication 与协调说明。
31. 实际示例 multi-agent-swarm 的 hook：`agent-stop-notification.sh` 检查文件存在（不存在快速退出），解析 `coordinator_session`、`agent_name`、`enabled`，若启用则向 coordinator 发送通知，并可通过 `enabled: true/false` 快速启停。
32. 实际示例 ralph-wiggum：`.claude/ralph-loop.local.md` 中设置 `iteration: 1`、`max_iterations: 10`、`completion_promise: "All tests passing and build successful"`；正文写要反馈的提示（如 Fix all the linting errors...）。
33. 实际示例 ralph-wiggum 的 hook：`stop-hook.sh` 检查文件存在（不活跃则快速退出），读取 `iteration` 和 `max_iterations`，提取 `completion_promise` 用于循环终止，读取正文作为反馈提示，并在每次循环更新 iteration 计数。
34. 快速参考：文件位置为 `project-root/.claude/plugin-name.local.md`；frontmatter 解析用 `FRONTMATTER=$(sed -n '/^---$/,/^---$/{ /^---$/d; p; }' "$FILE")`；正文解析用 `BODY=$(awk '/^---$/{i++; next} i>=2' "$FILE")`；快速退出用 `if [[ ! -f ".claude/my-plugin.local.md" ]]; then exit 0; fi`。
35. 设计设置 schema：确定字段、类型和默认值。
36. 在插件文档中创建模板设置文件。
37. 在 `.gitignore` 添加 `.claude/*.local.md`。
38. 在 hooks/commands 中实现设置解析。
39. 使用快速退出模式：检查文件存在、检查 enabled 字段。
40. 在插件 README 中记录设置和模板。
41. 提醒用户修改设置后需重启 Claude Code。
42. 保持设置简单，并在设置文件不存在时提供良好默认值。
43. 参考资源：阅读 `references/parsing-techniques.md` 和 `references/real-world-examples.md`；使用 `examples/read-settings-hook.sh`、`examples/create-settings-command.md`、`examples/example-settings.md`；使用 `scripts/validate-settings.sh`、`scripts/parse-frontmatter.sh`。

适用边界 · 注意事项

• 不适用于非 Claude Code 插件/hook/command/agent 体系，或没有 `.claude/` 目录与重启机制的开发环境。
• 如果配置需要纳入版本控制并在团队或用户间共享，不要用 `.local.md`，因为该文件应被 gitignore 且仅用户本地使用。
• 如果要求修改设置后无需重启即热生效，不适用，因为 hooks 不能在会话内热插拔。