Joan Workflow

Joan 是一个基于工作区的知识与任务管理系统，专为 AI 辅助开发设计。本技能涵盖如何在何时使用 Joan 的核心概念。

核心概念

工作区

工作区是 Joan 中最顶层的组织单元。每个工作区包含：

• Pods：版本化的领域知识文档
• Todos：作用于工作区的任务
• Plans：与任务关联的实现规范
• Members：具有角色（管理员、成员）的团队成员

Pods

Pods 是包含领域知识的版本化 Markdown 文档。请使用 Pods 来：

• 记录项目架构和设计决策
• 存储特定领域的术语和业务规则
• 在团队成员与 AI 助手之间共享知识
• 维护随项目演进的动态文档

Pod 生命周期：

1. 使用 joan pod create 在本地创建
2. 在 .joan/pods/ 目录中编辑 Markdown 文件
3. 使用 joan pod push 推送到服务器
4. 使用 joan pod pull 拉取最新内容

Todos

Todos 是作用于工作区的任务。请使用 Todos 来：

• 跟踪跨团队成员的工作项
• 分配任务并设置优先级
• 将实现计划与任务关联

Todo 工作流：

1. 使用 joan todo create 创建
2. 使用 joan todo list 列出
3. 随着工作进展更新状态
4. 完成后归档

Plans

Plans 是与 Todo 关联的实现规范。请使用 Plans 来：

• 记录某个功能的实现方式
• 将复杂任务拆解为具体步骤
• 与团队共享实现思路

CLI 命令参考

项目初始化

joan init                    # 交互式选择工作区
joan init -w <workspace-id>  # 非交互式，指定特定工作区
joan status                  # 显示项目与认证状态

Pod 管理

joan pod list               # 列出已跟踪的 Pods
joan pod list --all         # 列出工作区中所有 Pods
joan pod add                # 将工作区 Pods 添加到项目
joan pod create             # 在本地创建新 Pod
joan pod pull               # 从服务器拉取 Pods
joan pod push               # 将本地 Pods 推送到服务器
joan pod open               # 在浏览器中打开 Pod

Todo 管理

joan todo list              # 列出已跟踪 Pods 的 Todos
joan todo list --mine       # 列出分配给自己的 Todos
joan todo create            # 创建新 Todo
joan todo update <id>       # 更新 Todo 字段
joan todo archive <id>      # 归档已完成的 Todo

Plan 管理

joan plan list <todo-id>    # 列出某个 Todo 的 Plans
joan plan create <todo-id>  # 创建实现计划
joan plan pull <todo-id>    # 从服务器拉取 Plans
joan plan push <todo-id>    # 将 Plans 推送到服务器

上下文生成

joan context claude         # 生成包含 Joan 上下文的 CLAUDE.md

何时使用何种功能

启动新项目

1. 运行 joan init 将项目连接到一个工作区
2. 选择与项目领域相关的 Pods
3. 运行 joan context claude 将上下文注入 CLAUDE.md
4. 编码前阅读生成的 Pod 引用

编码前准备

1. 检查是否存在相关 Pods：joan pod list --all
2. 若缺少 Pods，执行 joan pod add
3. 拉取最新内容：joan pod pull
4. 阅读 Pods 以理解领域上下文

完成工作后

1. 考虑是否应将新学习成果整理为 Pod
2. 更新或创建 Todos 以反映进展
3. 推送本地更改：joan pod push 和 joan todo push

记录新知识

1. 创建 Pod：joan pod create
2. 在 Markdown 中撰写领域知识
3. 推送以共享：joan pod push
4. 更新 CLAUDE.md 上下文：joan context claude

MCP 集成

Joan 在 https://joan.land/mcp/joan 提供 MCP 服务端，支持以下工具：

• list_workspaces - 列出可访问的工作区
• list_pods - 列出工作区中的 Pods
• get_pod - 获取 Pod 内容

MCP 服务端使用 OAuth 2.1 认证。请先通过 CLI 执行 joan auth login 完成认证。

项目配置

Joan 将项目配置存储在 .joan/config.yaml：

workspace_id: <uuid>
tracked_pods:
  - name: "Pod 名称"
    id: <uuid>

Pods 本地存储于 .joan/pods/ 目录，以 Markdown 文件形式保存。

最佳实践

Pod 编写建议

• 使用清晰、描述性的标题
• 包含知识适用的上下文说明
• 保持每个 Pod 只聚焦一个领域概念
• 知识更新时同步更新 Pod
• 有帮助时引用相关 Pod

Todo 管理建议

• 创建粒度合适的 Todo（既不过大也不过小）
• 将 Todo 与相关 Pod 关联以提供上下文
• 及时更新状态，确保团队信息同步
• 完成后归档，减少干扰

上下文同步建议

• 更改已跟踪 Pods 后运行 joan context claude
• 开始重要工作前拉取最新 Pods
• 及时推送更改，与团队共享进展