1. 项目概述：一个为AI工具设计的Markdown原生多智能体工作空间

如果你和我一样，每天都在和Claude Code、Cursor或者OpenCode这类AI编程工具打交道，那你肯定遇到过这样的场景：想让AI帮你检查Kubernetes集群状态，或者分析PostgreSQL数据库的某个复杂查询，结果发现每次都要重新解释一遍项目的背景、架构规范、甚至团队内部的命名约定。更头疼的是，当项目涉及多个领域时，你需要在不同“角色”的AI助手之间手动切换和传递上下文，这个过程不仅低效，而且容易出错，上下文窗口的宝贵Token就在这种重复劳动中被白白浪费了。

今天要聊的Crux，就是为了解决这个痛点而生的。它不是一个全新的AI工具，而是一个运行在你现有AI工具（如OpenCode、Claude Code、Cursor）之上的 框架 。它的核心思想非常极客： 将一切规则、身份和协议都定义在纯文本的Markdown文件中 。这意味着，你可以为你的项目创建一套持久化的、可版本控制的“数字员工”体系。比如，你可以定义一个 @kubernetes-admin 智能体，让它专门负责所有与K8s相关的操作，它的知识库、行为准则、甚至沟通风格都固化在项目的 .crux/agents/kubernetes-admin/AGENT.md 文件里。同样，你还可以有一个 @postgresql-admin 智能体来管理数据库事务。

Crux的魅力在于它的“懒惰加载”和“纯文本”哲学。整个系统的运行逻辑对开发者是完全透明的——因为所有定义都是Markdown，你不需要启动任何运行时服务，就能读懂整个多智能体系统在干什么、怎么干。这对于追求可控性和可解释性的团队来说，价值巨大。它本质上是在LLM的“短期记忆”之上，为你的项目构建了一个结构化的、可检索的“长期记忆”和“组织架构”，让AI协作从临时的、一次性的对话，升级为有组织、有纪律的持续工程实践。

2. 核心架构与设计哲学拆解

2.1 为什么是“Markdown原生”与“无运行时”？

在深入目录结构之前，我们必须先理解Crux的两个基石性设计选择，这决定了它的使用体验和适用边界。

首先， “Markdown原生” 意味着所有智能体（Agent）、技能（Skill）、工作流（Workflow）甚至宪法（Constitution）都只是普通的 .md 文件。这带来了几个关键优势：

1. 极低的学习与接入成本 ：任何会写Markdown的开发者都能参与定义和修改智能体，无需学习新的DSL或配置文件格式。
2. 完美的版本控制 ： .git diff 可以直接展示智能体逻辑的变更，代码审查（Code Review）可以自然地覆盖AI行为规则的修改，实现了“Infrastructure as Markdown”。
3. 无供应商锁定 ：你的所有智能体定义是独立于任何特定AI工具或云服务的本地文件。今天用Claude Code，明天换到Cursor，你的智能体军团可以无缝迁移（通过Crux的转换脚本），知识资产不会丢失。

其次， “无运行时” 指的是Crux本身不包含需要常驻内存的守护进程、服务或API服务器。它的“运行时”其实就是你的AI工具（如Cursor）加载这些Markdown文件作为上下文的过程。这种设计的深层考量是 简化与透明 。

注意 ：这里的“无运行时”特指Crux框架本身。它依赖你的AI工具（如Cursor）作为执行引擎。Crux只负责组织上下文和流程，不负责调用LLM API或执行代码。这使它极其轻量，但也意味着它的能力边界受限于你所用的AI工具。

这种设计将复杂性从框架转移到了文件组织和上下文管理上。作为使用者，你的核心工作从“编程”变成了“写作”——为不同的任务角色撰写清晰、准确的职责描述（AGENT.md）和操作手册（SKILL.md）。

2.2 三层状态模型：静态、动态与会话

Crux通过清晰的目录结构，在物理层面划分了三种状态，这是理解其数据流和协作模式的关键。

第一层：静态层（ .crux/ 根目录下大部分文件） 这定义了系统“是谁”和“能做什么”。所有提交到Git仓库的文件都在这里。

• COORDINATOR.md , AGENTS.md ：框架的核心逻辑和项目级智能体概览。
• templates/ ：所有类型文件的模板，是创建新智能体或技能的起点。
• agents/{role-id}/ ：每个智能体的“身份证”和“行为手册”。 AGENT.md 包含了角色定义、系统指令和上下文预算。 onboarding.md 定义了该智能体首次启动时的初始化问卷。
• skills/{skill-name}/ ：原子化的任务单元。每个技能只做一件事，并且归属于一个特定的智能体。
• workflows/{name}.md ：多智能体协作的剧本。由协调器（Coordinator）解析并驱动多个智能体按步骤执行。

第二层：动态层（ .crux/workspace/ ） 这代表了系统“知道什么”，是运行时的状态，被 .gitignore 排除。

• MANIFEST.md ：系统的“总控台”。实时显示所有智能体的状态（如 onboarded , active ）、待批准的修订案（Amendments）和已注册的工作流。
• MEMORY.md (Coordinator) ：协调器的持久化记忆，存储跨会话的全局事实和决策。
• inbox.md ：人工审批队列。当智能体试图修改宪法（CONSTITUTION）或遇到无法决断的事情时，会在这里生成待办项，等待用户（你）处理。
• {role-id}/MEMORY.md ：每个智能体的私有持久化记忆。用于存储它在项目中学到的重要事实、做出的决策和形成的惯例。这是智能体“经验”的存放地。
• {role-id}/NOTES.md ：每个智能体的便签本。记录临时的操作问题、待办任务和新发现。

第三层：会话层（ .crux/workspace/*/sessions/{ulid}/ ） 这记录了“刚刚发生了什么”，是纯粹临时性的上下文缓存，用于单次交互。

• scratch.md ：本次会话的草稿纸，记录思考过程和中间结果。
• context-cache.md ：为优化Token使用而生成的上下文缓存。
• summary.md ：本次会话的摘要。

这种分层带来了巨大的灵活性。静态层保证核心逻辑可版本化、可协作；动态层让智能体在项目生命周期内持续学习和积累；会话层则确保了单次交互的高效和隔离。作为开发者，你大部分时间只需关心静态层的编写和动态层 inbox.md 的审批。

2.3 智能体、技能与工作流：职责分离的协作范式

Crux采用了经典的职责分离设计，将能力模块化，这是实现复杂多智能体协作的基础。

智能体（Agent）是“角色” 。它像一个数字员工，拥有固定的职责领域（如K8s运维）、特定的知识背景和沟通风格（定义在 SOUL.md 中）。它的核心文件 AGENT.md 就像一个岗位说明书，规定了它的核心指令、可用的技能列表，以及最重要的—— 上下文预算 。每个智能体在开始执行前，加载基础文件（宪法、灵魂、自身定义、记忆）就会消耗约2700个Token，这迫使设计者必须精炼描述，并为实际任务预留出足够的Token空间（总上限8000）。

技能（Skill）是“工具”或“流程” 。一个技能描述一项具体的、原子化的任务，例如“检查Pod状态”、“执行数据库备份”。技能文件 SKILL.md 包含输入参数、执行步骤、成功/失败条件以及输出格式。关键点在于， 一个技能只属于一个智能体 。这避免了权限混乱，确保K8s相关的技能只有 @kubernetes-admin 能调用，保持了系统的清晰度。

工作流（Workflow）是“剧本” 。当一项任务需要多个智能体接力完成时，就需要工作流。例如，一个“部署新微服务”的工作流可能涉及：1) @backend-dev 编写代码，2) @docker-expert 构建镜像，3) @kubernetes-admin 部署到集群。工作流文件 workflows/deploy-service.md 会定义步骤顺序、每个步骤负责的智能体和技能、以及步骤间的数据传递。协调器（Coordinator）负责读取这个剧本并指挥整个流程。

实操心得 ：在设计初期，最容易犯的错误是把智能体设计得过于“全能”。一个好的实践是，按照 领域驱动设计（DDD） 的思路，根据项目的核心子域来划分智能体。让每个智能体成为该子域的“专家”，它拥有的技能都应该是该领域内的具体操作。工作流则用于串联这些子域专家，完成端到端的业务流程。

3. 从零开始：安装、初始化与首个智能体创建

3.1 安装与环境适配

Crux的安装过程极其简单，这符合其“开箱即用”的理念。官方提供的一行命令安装脚本，会自动检测你当前目录使用的AI工具。

# 最简安装，脚本会自动检测你使用的AI工具（如Cursor）
curl -fsSL https://raw.githubusercontent.com/dotlabshq/crux/main/scripts/install.sh | bash

安装脚本的核心工作是创建项目根目录下的 .crux/ 文件夹，并将框架的核心文件（静态层模板、协调器逻辑等）复制进来。同时，它会根据检测到的AI工具，运行一个转换脚本（ convert.sh ），将通用的Crux智能体定义，转换成对应AI工具能识别的规则文件。例如，对于Cursor，它会生成 .cursor/rules/ 下的规则；对于Claude Code，则可能生成特定的配置文件。

但在一线实践中，自动检测有时可能不准，或者你希望进行更精细的控制。这时可以使用带参数的安装命令：

# 指定为目标AI工具安装（例如明确使用OpenCode）
curl -fsSL https://raw.githubusercontent.com/dotlabshq/crux/main/scripts/install.sh | bash -s -- \
  --tool opencode

# 只安装特定的智能体，例如你只需要K8s和数据库管理
curl -fsSL https://raw.githubusercontent.com/dotlabshq/crux/main/scripts/install.sh | bash -s -- \
  --agents kubernetes-admin,postgresql-admin

# 预览安装操作，而不实际写入文件（干跑模式）
curl -fsSL https://raw.githubusercontent.com/dotlabshq/crux/main/scripts/install.sh | bash -s -- \
  --dry-run

安装后检查 ：安装完成后，你的项目根目录下会出现 .crux/ 文件夹。此时，先不要启动AI工具。你应该先浏览一下 .crux/AGENTS.md 文件，这里列出了框架预置的智能体及其简介。同时，检查对应的AI工具配置目录下是否生成了规则，例如在Cursor项目中，查看 .cursor/rules/ 里是否有新生成的 .md 文件。

3.2 工作空间初始化与智能体入职

安装完成后，首次在你项目的目录下启动AI工具（比如打开Cursor），Crux的协调器逻辑就会被触发。此时，因为 .crux/workspace/MANIFEST.md 文件不存在或状态为 pending-onboard ，系统会进入 工作空间初始化 流程。

这个过程是交互式的，但设计得很智能：

1. 环境探测 ：协调器会先默默进行一系列检查（例如，查看是否有 package.json 、 Dockerfile 、 k8s/ 目录等），尽可能多地自动发现项目信息。
2. 交互式问答 ：对于无法自动获取的信息（如项目名称、核心业务目标、主要技术栈选择等），它会以对话形式向你提问。这些问题来源于 templates/onboarding.template.md 以及各个智能体自己的 onboarding.md 文件。
3. 文档生成 ：根据你的回答，协调器会调用相关智能体的技能，生成项目初始文档。例如，它可能让 @generalist 智能体生成一个项目概述文档（ .crux/docs/project-overview.md ），或者让 @architect 智能体生成一个初步的架构决策记录（ .crux/decisions/ADR-001.md ）。
4. 状态就绪 ：所有必要信息收集和文档生成完毕后，协调器会更新 MANIFEST.md ，将状态改为 onboarded ，并广播 agent.onboarded 事件。此时，各个智能体的 MEMORY.md 和 NOTES.md 文件也已创建并写入了初始内容。

关键点 ：这个入职流程是 按需且懒惰 的。并不是所有预置智能体都会立刻运行入职。只有当你首次 @mention （提及）某个智能体，或者某个工作流步骤需要它时，该智能体才会触发自己的入职流程。这避免了不必要的初始化开销。

3.3 创建你的第一个定制智能体

虽然框架提供了通用智能体，但Crux的真正威力在于为你自己的项目定制专属的数字员工。假设我们是一个前端项目，需要创建一个专门负责代码审查和ESLint规则维护的智能体 @frontend-guardian 。

步骤一：创建智能体身份文件 从模板复制并创建智能体目录和核心文件。

# 在项目根目录下执行
mkdir -p .crux/agents/frontend-guardian
cp .crux/templates/AGENT.template.md .crux/agents/frontend-guardian/AGENT.md
cp .crux/templates/onboarding.template.md .crux/agents/frontend-guardian/onboarding.md

接下来，编辑 .crux/agents/frontend-guardian/AGENT.md 。这个文件的结构分为三部分：

• Frontmatter (YAML头信息) ：定义智能体的ID、名称、所属工具和上下文预算。

  id: frontend-guardian
  name: Frontend Guardian
  tool: cursor # 指定主要适配的工具
  context_budget: 7500 # 该智能体的总Token预算，需预留出基础负载和任务空间
  

• 角色定义 ：这是核心，用自然语言清晰定义该智能体的职责、边界和知识范围。

  # Role: Frontend Guardian
  You are the dedicated code quality and consistency guardian for our React/TypeScript frontend project.
  Your primary domains are:
  1. **Code Review**: Focus on React best practices, hooks usage, component composition, and performance pitfalls.
  2. **ESLint & Prettier**: Maintain and explain our linting rules. Suggest updates when new community patterns emerge.
  3. **Bundle Analysis**: Keep an eye on import sizes and warn about potential bundle bloat.
  You are NOT responsible for backend API logic or infrastructure decisions. Defer those to @backend-dev or @kubernetes-admin.
  

• 技能列表 ：声明这个智能体拥有哪些技能。初始可以留空，或引用即将创建的技能。

  ## Skills
  - `review-react-component`
  - `explain-eslint-rule`
  - `analyze-import-cost`
  

步骤二：为智能体创建专属技能 智能体需要技能才能工作。让我们创建一个代码审查技能。

mkdir -p .crux/skills/review-react-component
cp .crux/templates/SKILL.template.md .crux/skills/review-react-component/SKILL.md

编辑 SKILL.md ，一个完整的技能模板通常包括：

• 描述与归属 ：技能是干什么的，属于哪个智能体。
• 输入/输出 ：明确需要用户提供什么（如文件路径），以及输出什么格式（如Markdown报告）。
• 执行步骤 ：一步步的指令，告诉智能体如何完成这个任务。这里可以写得非常具体，包括要检查的要点（如“检查是否使用了 useMemo 不当依赖”、“审查Props的类型定义是否严格”）。
• 错误处理 ：如果技能执行失败（如文件不存在），该如何回应。

步骤三：注册与同步 创建或修改智能体与技能文件后，必须运行转换脚本，使其生效。

./scripts/convert.sh

这个脚本会读取 .crux/agents/ 和 .crux/skills/ 下的所有变更，并将其同步到你的AI工具专属的配置目录中（例如，更新 .cursor/rules/ ）。现在，你可以在Cursor中通过 @frontend-guardian 来提及并使用它了。

避坑指南 ：在定义智能体角色时，最常见的错误是职责过于宽泛或模糊。例如，“负责前端开发”就是一个坏的定义。好的定义应该是具体、可行动的，如“负责React组件代码审查、维护ESLint配置一致性、并监控生产环境前端错误日志中的高频模式”。清晰的边界能大幅提升智能体响应的准确性和可靠性。

4. 核心机制深度解析：上下文加载、工作流与修订案

4.1 上下文加载顺序与Token预算管理

Crux最精妙的设计之一是其严格的上下文加载机制。它模拟了一个高效的“工作记忆”模型，确保智能体在行动前拥有必要且充足的信息，同时绝不超出LLM的上下文窗口限制。

当一个智能体被 @mention 触发时，它会严格按照以下顺序加载文件内容到上下文中，形成一个清晰的思维框架：

1. .crux/CONSTITUTION.md (~1000 tokens) ：项目的“根本大法”。定义了最高级别的原则、价值观、沟通规范和安全红线。所有智能体都必须无条件遵守。例如，“所有生成的代码必须包含单元测试”、“严禁使用已知不安全的依赖版本”。
2. .crux/SOUL.md (~500 tokens) ：项目的“团队文化”。定义了沟通风格、协作偏好和共同术语。例如，“我们倾向于使用务实的、直截了当的沟通方式，避免冗长的客套话”、“我们将‘用户’称为‘客户’”。
3. .crux/agents/{role}/AGENT.md (~800 tokens) ：智能体的“岗位说明书”。如前所述，包含其专属职责、边界和技能列表。
4. .crux/workspace/{role}/MEMORY.md (~400 tokens) ：智能体的“长期记忆”。存储了它在过往交互中学到的关于本项目的重要事实、做出的关键决策和达成的惯例。例如，“本项目使用 axios 作为HTTP客户端，且已在 src/lib/axios.ts 中配置了全局拦截器”。

以上四部分是 基础负载 ，总计约2700个Token。这意味着，在智能体开始思考你的具体问题之前，它已经“知道”了自己在哪个团队（宪法）、团队氛围如何（灵魂）、自己的岗位是什么（AGENT），以及自己过去在这个项目上积累的经验（MEMORY）。

在此之后，根据任务需要，按需懒惰加载： 5. .crux/workspace/{role}/NOTES.md ：加载当前待解决的问题和任务列表。 6. .crux/summaries/{doc}.md ：如果需要参考某个长文档，先加载其摘要以获取概览。 7. .crux/docs/{doc}.md ：如果摘要信息不足，再加载完整的文档。 8. .crux/decisions/{id}.md ：当任务涉及某个历史决策时，加载对应的决策记录。 9. .crux/skills/{name}/SKILL.md ：当执行特定技能时，加载该技能的详细步骤指南。 技能在执行后会被卸载 ，以释放Token空间。

整个上下文的硬上限是 8000个Token 。这个限制强制进行了良好的信息架构设计。如果你的 AGENT.md 写得过于冗长，就会挤占用于加载具体任务文档（如 docs/ ）的空间。因此，编写精炼、准确的描述不仅是为了清晰，更是为了功能性。

4.2 多智能体工作流的编排与执行

单一智能体处理复杂任务的能力是有限的。Crux的工作流（Workflow）机制使得串联多个智能体成为可能，实现“流水线”作业。

一个工作流文件（例如 .crux/workflows/deploy-feature.md ）本质上是一个Markdown格式的剧本。其结构通常如下：

# Workflow: Deploy a New Feature
**Trigger Phrase**: “deploy feature”
**Owner**: @coordinator

## Step 1: Code Review & Test
**Agent**: @frontend-guardian
**Skill**: review-react-component
**Inputs**:
- `file_path`: `src/components/NewFeature.tsx`
**Required**: Yes
**On Failure**: stop

## Step 2: Build & Package
**Agent**: @devops-engineer
**Skill**: docker-build-frontend
**Inputs**:
- `tag`: `feature-${feature-branch-name}`
**Required**: Yes
**On Failure**: rollback_step_1 # 定义回滚动作，例如通知@frontend-guardian

## Step 3: Deploy to Staging
**Agent**: @kubernetes-admin
**Skill**: deploy-to-namespace
**Inputs**:
- `namespace`: `staging`
- `image_tag`: `[output from step 2]`
**Required**: Yes
**On Failure**: rollback_step_2

当用户在对话中说出触发短语“deploy feature”时，协调器会：

1. 加载并解析对应的工作流文件。
2. 按顺序收集每个步骤所需的输入（可能会与用户交互确认）。
3. 对于每一步，检查负责的智能体是否已“入职”（状态为 onboarded ）。如果该步骤是必需的（ Required: Yes ）而智能体未就绪，则工作流停止。
4. 通过 @mention 将任务委托给指定智能体，并传入输入参数。
5. 记录该步骤的结果到协调器的会话草稿（ scratch.md ）中，并将输出作为可能的下一步输入。
6. 所有步骤成功后，协调器进行“最终确认”，更新系统状态并广播事件。
7. 如果某必需步骤失败，则执行该步骤定义的回滚操作。

实操心得 ：设计工作流时，尽量让每个步骤是“幂等”的，并且步骤间的耦合要低。通过工作流的 Inputs 和 Outputs 来传递数据，而不是让智能体直接去修改共享的中间文件。这能让整个流程更健壮，也更容易调试。同时，善用 Required 字段，对于一些非核心的、可选的检查步骤（如“生成代码覆盖率报告”），可以设为 No ，这样即使该智能体未配置或暂时出错，工作流也能继续。

4.3 宪法修订案（Amendment）流程：动态演进的安全阀

项目规则不是一成不变的。随着项目发展，可能需要调整 CONSTITUTION.md 中的某些原则。Crux通过一个严谨的 修订案（Amendment）流程 来管理这种变更，确保人类始终拥有最终控制权。

流程如下：

1. 提案 ：智能体在运行过程中，如果认为某条宪法规则需要修改（例如，发现一条新的安全规范），它不会直接修改 CONSTITUTION.md 。相反，它会在 .crux/workspace/MANIFEST.md 文件的“Pending Amendments”部分，写入一个修订案提案（ AMD-{id} ），说明修改理由、旧条款和新条款。
2. 暂停与通知 ：提出修订案后，该智能体会暂停后续操作，并通过 inbox.md 文件通知用户：“我有一个关于宪法的修订提议，等待您的审批”。
3. 人工审批 ：用户（开发者）查看 inbox.md ，评估这个修订案。可以同意、拒绝，或者提出修改意见。
4. 执行决策 ：
   • 批准 ：用户批准后，协调器会自动更新 CONSTITUTION.md 文件，增加版本号，并记录此次修订。然后智能体基于新宪法继续工作。
   • 拒绝 ：用户拒绝后，智能体会收到通知，并继续在现有宪法规则下运行。

这个机制是Crux“人类在环”（Human-in-the-loop）理念的核心体现。它将AI的主动性（可以提出改进建议）与人类的最终裁决权完美结合，既允许系统动态演进，又杜绝了AI擅自更改核心规则的风险。对于团队协作来说，这个流程也天然地形成了代码审查，任何对项目根本规则的修改都必须经过人工确认。

5. 高级实践、问题排查与效能优化

5.1 维护与同步：团队协作场景下的最佳实践

Crux框架本身和预置的智能体定义都在上游GitHub仓库中。当你基于Crux管理一个团队项目时，如何同步框架更新，同时管理自定义的智能体，是一个必须考虑的问题。

更新框架与公共智能体 使用内置的更新脚本，可以拉取上游Crux仓库的最新改动。

# 更新所有内容（框架文件、所有agents/、skills/）
./scripts/update.sh

# 仅更新指定的智能体（避免不必要的覆盖）
./scripts/update.sh --agents kubernetes-admin,postgresql-admin

# 干跑模式，预览将要更新的文件
./scripts/update.sh --dry-run

重要警告 ： update.sh 脚本会 覆盖 .crux/agents/ , .crux/skills/ 和框架核心文件。如果你在这些目录下有自己的定制内容，它们会被上游版本覆盖。因此，最佳实践是： 永远不要直接修改Crux预置的智能体文件 。如果你需要调整一个预置智能体，应该将其复制到你的项目私有目录（可以放在项目根目录下另一个文件夹，如 my-agents/ ），然后修改 .crux/AGENTS.md 中的引用，或者创建你自己的、继承其功能的新智能体。

管理自定义智能体与技能 你的项目专属智能体和技能应该被视作项目源代码的一部分，与其他代码一起进行版本控制。

1. 独立目录 ：考虑在 .crux/ 之外（例如项目根目录下）创建一个 team-agents/ 目录，存放团队自定义的智能体和技能。这样可以清晰地区分上游框架和本地定制。
2. 符号链接 ：在 .crux/agents/ 或 .crux/skills/ 目录下，为你自定义的内容创建符号链接（symlink）指向 team-agents/ 里的实际文件。这样， convert.sh 脚本仍然能发现它们，而 update.sh 脚本又不会覆盖它们。

   ln -s ../../team-agents/frontend-guardian .crux/agents/frontend-guardian
   

3. 文档化 ：在团队README或 .crux/AGENTS.md 中，明确记录哪些是自定义智能体，其职责和创建原因是什么。

Git策略 Crux的 .gitignore 文件已经排除了整个 .crux/workspace/ 目录，因为那里是动态运行时状态。你应该提交以下内容：

• 整个 .crux/ 目录（除了 workspace/ ）。
• 你的自定义智能体目录（如 team-agents/ ）。
• 项目根目录的 README.md ，其中应包含如何使用本项目Crux设置的说明。

5.2 常见问题与排查实录

在实际使用中，你可能会遇到一些典型问题。以下是一些排查思路：

问题1：@mention智能体无反应或AI工具不认识该指令。

• 检查点1：转换脚本 。确保在创建或修改智能体后运行了 ./scripts/convert.sh 。这个脚本负责将Crux定义“翻译”成AI工具能理解的规则。去检查你的AI工具规则目录（如 .cursor/rules/ ）下是否有对应的新文件。
• 检查点2：智能体状态 。查看 .crux/workspace/MANIFEST.md ，确认该智能体的状态是否为 onboarded 。如果是 pending-onboard ，你需要先与它进行一次对话，完成其入职流程。
• 检查点3：上下文加载 。AI工具可能有自己的上下文加载规则或冲突的全局指令。检查AI工具的主设置，确保没有禁用或覆盖项目级规则。

问题2：智能体行为不符合预期，或者忘记了之前约定的事情。

• 检查点1：MEMORY.md 。智能体的长期记忆存储在 .crux/workspace/{role}/MEMORY.md 。检查这个文件，看它是否正确地记录了过去的重要决策或事实。有时文件可能因为写入冲突而损坏。
• 检查点2：宪法与灵魂冲突 。检查 CONSTITUTION.md 和 SOUL.md ，看是否有更高层级的规则覆盖或限制了智能体的行为。智能体必须优先遵守宪法。
• 检查点3：Token超限 。智能体的总上下文可能接近或超过了8000 Token的限制，导致部分关键信息（如技能步骤）被截断。尝试精简 AGENT.md 的描述，或者将一些不常用的参考信息移到 docs/ 目录中，改为按需懒惰加载。

问题3：工作流执行到某一步卡住或失败。

• 检查点1：会话草稿 。查看协调器或对应智能体的当前会话目录下的 scratch.md 文件（路径如 .crux/workspace/sessions/{最新ULID}/scratch.md ）。这里通常记录了执行过程中的详细思考和中间输出，是排查问题的第一现场。
• 检查点2：输入/输出格式 。检查工作流步骤中定义的 Inputs ，是否与对应技能 SKILL.md 中期望的输入格式完全匹配。一个常见的错误是参数名拼写不一致或数据类型不符（例如，技能期望一个文件路径字符串，但工作流传递了一个对象）。
• 检查点3：智能体可用性 。确认工作流步骤中指定的智能体ID完全正确，并且该智能体已成功入职（状态为 onboarded ）。

问题4： inbox.md 中堆积了大量待审批项，或者修订案流程不触发。

• 检查点1：inbox文件状态 。 inbox.md 是一个动态文件，需要你定期查看和处理。处理完一项后，可以将其标记为完成或删除。协调器只负责写入，不负责清理。
• 检查点2：修订案权限 。只有涉及修改 CONSTITUTION.md 的行为才会触发修订案流程。智能体修改自己的 MEMORY.md 或生成 docs/ 文件不需要审批。确认智能体试图修改的是否是宪法条款。

5.3 效能优化与扩展思路

当你的Crux系统变得庞大，拥有数十个智能体和技能时，以下优化策略能提升体验：

1. 精细化上下文预算管理 为每个智能体的 AGENT.md 中的 context_budget 设置一个合理的值。对于需要处理大量文档的智能体（如 @researcher ），可以给到7500+；对于执行简单、原子化任务的智能体（如 @formatter ），可以降低到5000。在 AGENT.md 中，明确指示智能体优先从 summaries/ 加载信息，只有必要时才加载完整的 docs/ 。

2. 技能设计的“单一职责”与“可组合性” 技能应该像Unix哲学下的工具一样：做好一件事，并通过清晰的接口（输入/输出）进行组合。避免创建“巨无霸”技能。例如，不要创建一个“处理用户注册”的技能，而是拆分成 validate-user-input 、 create-database-record 、 send-welcome-email 三个小技能。这样它们可以被不同工作流灵活复用。

3. 利用 MEMORY.md 构建知识图谱 鼓励智能体将重要的、结构化的发现写入自己的 MEMORY.md 。你可以定义一种简单的格式，例如使用YAML Frontmatter或特定的Markdown标记，以便未来通过脚本或另一个智能体进行分析，从而构建起项目的动态知识图谱。

4. 创建“管理型”智能体 你可以创建一个 @crux-maintainer 智能体，它的技能包括：

• list-all-agents : 列出所有智能体及其状态。
• diagnose-agent-failure : 分析某个智能体最近会话的 scratch.md 来诊断问题。
• suggest-context-optimization : 分析各智能体的上下文使用情况，并提出优化建议。 这个智能体本身不参与业务逻辑，而是作为Crux框架的“管理员”，帮助你更好地管理和维护这个多智能体系统。

Crux不是一个一蹴而就的魔法盒子，而是一个需要精心设计和持续调优的协作框架。它最大的回报在于，随着时间推移，你的项目不再只是一堆代码和文档，更是一个积累了丰富领域知识、拥有明确分工、并能自动执行复杂流程的“数字组织”。这个组织的规则完全由你定义，并以最透明、最可维护的方式——纯文本Markdown——保存下来。