Linear

我有一个代码代理——Claude Code，每月与我的问题跟踪工具Linear交互大约800次：列出任务、创建问题、更改状态、发表评论。我检查了其中165次会话，并统计出了超过500个错误和超过370次重试。 这些错误没有一个是Linear的API故障引起的，全部都是接口错误：代理与命令行通信，但命令行无法理解。 保守估计，每月大约浪费了70万个token仅仅是与工具“斗争”：重试、读取错误信息、纠正再尝试。这种无形的成本不会出现在任何账单中，但却存在于每次会话中。 背景：代理现在是主要用户 命令行工具（CLI）——从历史上看，是为人类设计的。而人类用户是非常灵活的。如果一个命令失败了，他们会通过 --help 查看帮助。如果错误信息很难理解，他们会去查阅文档。如果该工具有某些特性，他们会记住并避免再犯同样的错误。 而AI代理基本不会这么做。它在不同会话之间不会积累经验，也不会投入太多精力去阅读文档。当某些操作失败时，它也不会深入分析问题所在，而是根据认为最有可能的方式尝试再次执行。 这改变了你的工具客户是谁的定义。如果代理每月调用该工具800次，而你手动使用它只有三次，那么这个接口的主要使用者就是代理。为了人类用户设计工具并期待代理能适应，这是在为次要用户优化。 为这个主要用户专门设计有一个名字：智能代理体验（agentic experience）。它之于代理，正如用户体验（UX）之于人类用户，开发者体验（DX）之于API的开发者。更重要的是，一种最有效的测量工具早已存在——代理的错误日志。 错误有其规律 我将所有以非零退出代码结束的CLI调用定义为错误。根据这一标准，这500多个错误并非随机发生：几乎全部集中在三个模式中。 错误模式 代理行为 设计暴露的问题 虚构的标志 输入 --status 而非 --state；--priority urgent 而非 --priority 1 真正的标志不是人们会优先猜到的名称 缺少的操作过程 尝试搜索文本、按项目筛选或在创建时分配项目：CLI不具备这些功能 工具未涉及实际的工作流程 忘记必要的标志 忽略 --sort，--no-pager，--no-interactive 要求人工决策，而工具本可以自动处理 当代理输入 --status 时，它并非胡乱猜测，而是在推测出最可能的接口名称。--status 和 --state 都非常合理。而我设计的CLI并未与这种直觉一致。 还有一个问题没有反映在统计数据中，因为它不会导致命令失败：冗长的输出。CLI以JSON格式返回列表，每个问题大约50个token。如果命令成功返回（退出代码为零），这类问题就不会被统计为错误；但长列表和每月800次调用叠加起来，这就是那70万个token成本的另一半。这种成本往往被忽视，因为不会妨碍任务完成。 重新审视错误 容易的解释是直接了当的：代理在错误使用工具。这是错误的解释，应逐一反驳。 虚构的标志表明真正的标志名称不够直观。忘记的必要标志表明这些标志完全不应该是必要项：如果工具可以推测出合理的默认值，那么强制要求填写这些标志只会额外增加使用者的工作量。一段没有用的输出或者产生过多token意味着选错了应对的输出格式。 代理的错误日志不是错误列表，而是一个规范: 每个错误都“否定性”地描述了你原本该如何设计接口。而这个规范是你最真实的反馈：无需代价，无数的真实数据，且没有人为善意隐藏工具缺陷。一个人类用户遇到糟糕的CLI时，可能会保持沉默并自动适应它。但代理不会适应：它会一遍又一遍地犯同样的错误，并记录下每一次。 这与我在另一篇文章中提出的一个原则有关：不应允许错误路径存在，而非仅仅禁止其使用。禁止只是一种文档说明——“不要使用--status“——而文档取决于是否有人认真阅读。让错误变得不可能，是设计的职责。 因此，解决方案并非更好的文档，而是更好的工具。 重设计 我围绕这个原则重写了CLI，工具叫做lql。以下四个设计决策贯穿整个改进过程。 宽容优于拒绝。 如果代理输入了 --status，工具会将其接受为 --state 的别名并继续运行。如果输入了 --priority urgent，将其解析为 --priority 1 并说明假定的结果。最常见的“错误”路径直接被转变为正确路径。工具不会因为合理的猜测而惩罚用户，而是直接适应它。 通过错误信息指导正确方向。 当某个功能确实不存在时，错误信息不会简单地说 unknown flag，而是给出具体指导：--filter 不存在。要按状态筛选，请使用：--state <状态>。要搜索，请使用：lql search "文本"。 错误消息本身变成了文档，并且恰好呈现在用户最专注的时间点：他们刚刚失败时。 取消所有强制标志。 lql list 无需提供任何参数即可运行：默认按优先级排序，筛选出活跃状态，并根据工作目录自动检测团队。因为不存在 --sort 参数，自然也就没有遗漏它的可能性。一个代理无法忘记不存在的标志。 ...

TL;DR: Linear 推出了一个集成的人工智能代理。听起来不错，但它并没有解决开发者在终端操作 coding agents 时的痛点。我们需要的不是另一个代理，而是一个可靠的 CLI，我们现有的代理可以直接调用。如果要重写，那就用 Rust——这就是 lql 的由来，一款专为 Linear 设计、面向代理的 CLI。 昨天，Linear 宣布了他们的人工智能代理。这是一个集成到应用中的聊天机器人，能够理解你的 roadmap，你的 issue 和你的代码。你可以在 Slack 上与它对话，在评论中@提到它，它会综合上下文，建议行动方案，甚至直接为你创建 issue。 听起来很棒。真的，很棒。 尽管如此，当我读到这个公告时，我的第一反应是：“这不是我需要的东西。” Linear 的大冒险 为了让你明白我的意思，我需要先讲讲背景。我和 Linear 的关系就像一部委内瑞拉肥皂剧一样，是一段充满了爱恨交织的故事。 第一幕：MCP 服务器。 Linear 曾经有一个 MCP 服务器，供人工智能代理与其交互使用。它的表现就像是在飓风里点打火机：技术上是能点着火，但火焰从来维持不到两秒。断断续续、缓慢，偏偏总是在关键时刻掉链子。最终我直接把它卸载了。 第二幕：GraphQL API。 于是唯有通过 GraphQL 直接和 Linear 沟通。没错，它确实能用，直到你需要在某个 issue 的描述中加入特殊字符，结果这些字符的转义问题会让你重新思考自己的整个人生。某一次，我花的时间转义一个括号比写 issue 所描述的代码还要长。 第三幕：Linear CLI。 然后 linear CLI 出现了，这是一个由社区开发的项目。brew install schpet/tap/linear 然后直接运行。一个第三方工具，朴素、不显眼，但正是我需要的工具：能够直接在终端创建、列出并更新 issue，而不需要与 GraphQL 或那个让人发疯的 MCP 作斗争，也没有弹窗干扰。 我甚至专门写了一篇文章 讲述自己如何用这个 CLI 解放了工作流。一个简单的 bash 脚本帮我在不到一分钟内创建了 49 个 issue。如果用 MCP，我可能会花上一个半小时。 进入代理 现在 Linear 推出了他们的代理。这款产品承诺：一个可以理解你的工作空间、与你的代码连接并自动化你的工作流程的集成助手。 ...

2004年，劳伦斯·莱西格（Lawrence Lessig）给他的所有联系人发了一封群发邮件，大意是：“抱歉，我把你们所有的邮件都删了。如果有什么重要的事情，请再发一次。” 当时，他已经花了整整80个小时清空从2002年积累下来的收件箱。他每天收到200封邮件。 莱西格并不是个不善管理的人——他是斯坦福大学法律学院的教授。然而，即便如此，他仍然败给了电子邮件。 我至少宣布过三次邮件破产。第一次让我感到如释重负。第二次让我觉得自己很狼狈。第三次让我意识到问题根本不在我自己。 电子邮件是一个任何人都可以填满的收件箱 好好想想。你的收件箱是一个地球上任何人都可以随意修改的任务列表。你的老板、你的银行、你四年前在某次会议上认识的一个人、你醉酒时订阅的某个电子邮件新闻简报，还有Jira的一个机器人提醒你某人刚刚把一个任务从“待处理”挪到了“进行中”。 所有人都可以往你的任务列表里塞东西。没有人会问你是否有时间。 就好像你把家门敞开，门口挂个牌子写着“想让我干什么就放这儿吧”。然后你还会惊讶地发现门口堆满了包裹。 被过度滥用的工具 电子邮件的发明初衷是用来传递消息的。一条消息。从一个点到另一个点。就像信件，只是更快罢了。到这一步，一切都好。 但问题是，人类把它变成了什么： 电子邮件本来的用途 我们把它变成了什么 一个消息传递系统 一个任务列表 异步通信 “你有没有看到我5分钟前发给你的邮件？” 点对点沟通 抄送47个人，“以防万一” 纯文本邮件 带有追踪像素和动态GIF的HTML邮件 沟通工具 CRM、文件管理器和法律档案库的集合 用通俗点的话说：我们拿了一把锤子，却把它当成螺丝刀、黄油刀和开瓶器来用。然后又抱怨它的把手坏了。 混乱的数字 加州大学尔湾分校的一项研究发现，我们在被严重打扰后需要花23分钟15秒才能重新集中注意力。而普通员工平均每小时检查电子邮件36次。也就是说，每小时就可能有36次干扰。 算一算账：如果你每次查看电子邮件都会损失2分钟的工作状态转换时间，那你每天仅仅因为查看新邮件，就可能浪费超过1小时。不是为了阅读邮件，也不是为了回复邮件，仅仅是切换注意力。 这就像是每100米就突然猛转方向盘。这确实可以前进，但却是耗费了双倍的油，同时精疲力尽。 邮件破产行不通（你也知道） 每次我宣布电子邮件破产时，循环总是一样的： 第一周： 收件箱变为空，无比平静，精神得以解脱。“这次我一定行。” 第二周： 收件箱里有47封未读邮件。“我一会儿再看。” 第三周： 收件箱有200封邮件。一些很重要。我开始眯着眼扫主题。 第四周： 500封邮件。我已经不知道哪些看过哪些没看。焦虑突升。 第三个月： 又宣布破产。 问题不是你不够有条理。问题在于，把电子邮件当作任务管理和提醒系统是结构性地站不住脚的。这个系统既没有优先级，也没有截止日期，更没有状态变化。它无法区分“有空再看”和“今天不回复你就丢了大单”。 一切内容都会以相同的形式，通过同一个入口，排成一条以“最近有人联系你”为顺序的无限列表。这不是什么生产力系统。这是一个时间消耗的垃圾场。 更好的解决方案并不是更好地管理 email 我尝试过各种方法。Gmail的过滤器。像地铁线路图一样的颜色编码标签。邮件“稍后提醒”。文件夹命名为“今天要回复”“这一周要处理”“闲时阅读”（剧透一下：所谓的“闲时”从来不会来）。我还用过FollowUpThen，你可以把一封邮件转发到3days@followupthen.com，然后它会在3天后把邮件发回你的收件箱。 你知道用FollowUpThen后会发生什么吗？那就是：现在你的收件箱里不仅有原始邮件，还有提醒邮件。解决邮件过量问题的方法，反而制造了更多邮件。这就像想用汽油灭火一样。 真正的解决方法是：将提醒和跟进行动从邮件里完全分离出来。 没有模棱两可，只能彻底剥离。 Memento：虽无趣却有效的解决方法 我的第一个解决方案叫做Memento。它不是一个带漂亮界面和订阅计划的应用程序。它是一个只有120行代码的Python脚本，用来查询Linear（我的任务管理工具），告诉我有哪些事项超出了截止日期。 # GraphQL 查询：筛选出过期但未完成或取消的任务 issues(filter: { dueDate: { lte: "2026-03-11" }, state: { type: { nin: ["completed", "canceled"] } } }) --- 就是这样了。一段简单的查询字符串：**“有哪些我本该做但却没做的事情？”** 我用终端运行这个命令来查看： ```bash uv run memento 然后就会显示类似这样的内容： ...

不到一个月前，我写了篇完整文章介绍如何在Claude Code中使用三层记忆系统：Linear负责战略、Beads负责战术、Tasks负责执行。构建了一个优雅的金字塔模型。 然而现实很骨感。 今天我正式退役Beads。这不是心血来潮，而是因为这个工具制造的麻烦已经超过了它解决的问题——它不再是工具，而是累赘。 Beads的初衷 对于没读过前文的读者，Beads是一个基于Git的issue跟踪器。作为Claude Code的插件，它将issues存储为代码库中的JSONL文件。理论上设计很精妙： Git持久化：issues保存在.beads/目录并与代码一起提交 依赖管理：支持issue间阻塞关系 离线工作：无需网络连接 LLM原生支持：直接读取文件，无需API配置 其核心价值是作为"本周计划"(Linear)和"当前任务"(Tasks)之间的战术衔接层。 故障始末 起初一切顺利，直到各种创意故障接踵而至。 恶魔守护进程 Beads依赖后台守护进程管理SQLite数据库并与Git同步。听起来合理？实际状况： 检测到数据库不匹配！ 当前数据库属于其他代码库： 数据库记录库ID：d1f9ca0c 当前代码库ID：01eac8ea ⚠️ 严重警告：此错误可能导致同步时误删issues！ 这个错误会在每次会话启动时出现。守护进程崩溃、同步失败，导致issues陷入量子态——既存在于本地SQLite又不存在于Git，反之亦然。 幽灵同步 bd sync本应同步Git远程仓库的issues，但经常失效： → 从远程拉取中... 错误：git pull执行失败：退出状态1 remote: 仓库不存在 fatal: 无法访问'https://git.frr.dev/frr/wuwei.git/' 当代码库配置多个remote时（这很常见），Beads可能选错远程仓库。若该仓库不存在或已更名，每次操作都会静默报错。最终issues停止同步，直到下次会话时数据全部消失才后知后觉。 认知损耗 每次Claude Code会话都这样开始： Claude读取Beads提示（通过hooks注入） 尝试启动守护进程 因数据库不匹配失败 Claude尝试bd sync 因远程仓库错误失败 你手动输入"忽略该错误" 终于可以开始工作 六个摩擦步骤消耗着上下文、时间和耐心。 局势转变 两件事让Beads从"带bug的实用工具"沦为"不必要的负担"： 1. Tasks的成熟 当初设计三层架构时，Tasks功能简陋。现在已具备： 支持描述和元数据的TaskCreate 带依赖关系的TaskUpdate 查询功能TaskList/TaskGet 通过CLAUDE_CODE_TASK_LIST_ID实现跨会话持久化 简言之：Tasks现已实现Beads的所有会话内功能，且无需守护进程、SQLite或Git同步。 2. Linear CLI问世 原生的Linear管理控制台(MCP)往好了说也很糟糕——延迟高、稳定性差，总在关键时刻掉链子。 直接调用GraphQL API？理论上可行，直到你需要在issue描述中使用特殊字符： # 尝试1：使用bash字符串插值 # 结果：括号和箭头破坏JSON结构 # 尝试2：Python urllib方案 # 结果：因op read无法在Python环境执行报401错误 # 尝试3：默默流泪 # 结果：情绪宣泄但无实际产出 直到发现linear命令行工具： ...