organize-ai-context 用于帮助任意代码仓库整理面向 AI 智能体的项目上下文，把分散或非结构化的指南归置到标准文件中。适用场景包括新仓库初始化，或希望重新对齐既有仓库的项目上下文。官方建议定期运行，持续维护上下文，好比给花园除草。
任务管理是强制前置步骤：执行任何操作前，必须先运行 bd prime 检查仓库是否使用 BEADS。若使用 BEADS，必须用 bd issue tracker 管理全部任务，不得使用 todowrite 或自定义 markdown 文件；若未使用，则用 todowrite 工具（不可用时用本地 markdown 文件或任务跟踪器）先建立清晰的工作清单。
文件划分规则要求不得把架构、开发指南、测试规则或安全策略合并进单一文件或根部 CLAUDE.md，它们必须在 docs/ 目录下分开存放。每个仓库起始状态应包含独立文件：CLAUDE.md（全局规则、命令参考与上下文索引，保持精简且少于 100 行）、AGENTS.md（只读指针，仅用于指向 CLAUDE.md）、docs/ARCHITECTURE.md（系统组件、数据流、数据库模式与目录结构）、docs/DEVELOPMENT.md（编码规范、命名、设计原则与错误处理）、docs/PRODUCT.md（需求、用户故事与成功标准）、docs/SECURITY.md（环境变量、API 密钥策略与认证姿态）、docs/TESTING.md（测试要求、运行方式与缺陷修复策略）。任何 docs/*.md 超过约 200–300 行时，应重构为索引/指针文件，将详细内容移入子目录，并在主文件中保留高层摘要与链接。
使用方式分三阶段：扫描阶段用 read、glob、bash 分析根配置文件、测试目录与现有文档；交互阶段通过提问确认技术栈、架构入口、设计模式及测试与缺陷修复策略；生成阶段起草并写入上述文件。每个主文件顶部必须要求相应的主题声明，以对齐当前与未来内容。
在 CLAUDE.md 中，全局规则必须集中在唯一的“## CRITICAL Rules”标题下，不得另建其他规则区；非全局规则应放入对应的 docs/* 文件。该标题格式必须为：## CRITICAL Rules，后跟 > [!IMPORTANT] 引用块。应建议的最佳实践包括：Git 提交仅用单行 git commit -m "..."，不用 heredoc 或 Co-Authored-By，优先 Conventional Commits；Bash 语法检查使用 bashcheck，不用 bash -n；任何改动后运行测试；缺陷修复遵循 docs/TESTING.md 的 TDD 策略；创建新技能使用 superpowers:writing-skills 技能。必须保留并合并用户已有的规则，不得静默丢弃。
常见错误包括：把一切塞进根 CLAUDE.md；将 docs/DEVELOPMENT.md 与 docs/TESTING.md 合并；覆盖文件时丢失用户规则；忘记先用 bd prime 检查 Beads；在非 Beads 仓库运行 bd；生成不匹配本地技术栈的通用规则。当仓库结构特别不规范或过大时，官方建议更多依赖交互式问卷，而非错误猜测。