linear

Linear

概述

如果有 Linear CLI（linear），请使用它。不要假定它已安装。CLI 不可用或不支持所需操作时，请使用环境已提供的 API 密钥调用 Linear 的 GraphQL API。

选择访问方式

1. 检查 CLI 是否可用，不要让检查失败：

   command -v linear
   

2. 如果 CLI 存在，请按照下方的 CLI 指引操作。

3. 否则，请在不打印凭据的情况下，确认 GraphQL 凭据是否可用：

   test -n "${LINEAR_API_KEY:-}"
   

   使用 direnv 的项目通常会在一个被忽略的环境文件中声明 LINEAR_API_KEY，并从 .envrc 加载它。如果缺少该变量，请让 direnv 加载项目环境（例如进入或允许该项目，或使用 direnv exec），不要读取、记录或复制该密钥。

4. 向 https://api.linear.app/graphql 发送 GraphQL 操作，并使用 Authorization: $LINEAR_API_KEY 和 JSON 内容类型。请使用 GraphQL 变量，而不要将问题文本插入查询：

   query='query Viewer { viewer { id name email } }'
   payload=$(jq -cn --arg query "$query" '{query: $query, variables: {}}')
   response=$(curl -sS https://api.linear.app/graphql \
     -H "Authorization: $LINEAR_API_KEY" \
     -H 'Content-Type: application/json' \
     --data "$payload")
   jq -e '.errors == null' <<<"$response" >/dev/null || {
     jq '.errors' <<<"$response" >&2
     exit 1
   }
   jq '.data' <<<"$response"
   

对于变更操作，请先查询 ID 和当前状态，不要猜测或依赖过时的硬编码 ID。包含 errors 数组的 GraphQL HTTP 200 响应应视为失败。切勿打印 API 密钥、将其包含在命令输出中、提交密钥，或直接将其放入查询或变量对象。

编写问题

创建、起草、改写或扩展问题的请求，授权范围仅限于忠实记录问题，而非产品规划或解决方案设计。问题应说明需要解决的问题，并将实现方案的探索留给负责这项工作的人员或 Agent。

默认格式

每个问题正文都以一个简短的通俗段落开头：

> **In plain terms:** Describe what is wrong or missing, who or what it affects, and why it matters. Do not prescribe the implementation.

此段必须独立成文，方便非专业读者理解。如果请求仅包含一个句子，问题可以只包含这一句。只有在来源材料足以支持时，才添加更多章节。

核心原则

• 先说问题，再说解决方案。 描述当前行为、已知的用户或运营预期结果、受影响的人员或系统、影响以及有用的证据。标题应说明问题或预期结果，而不是实现任务。
• 只写有来源的事实。 仅纳入由用户陈述、引用来源中明确说明或直接核实的细节。保留不确定性，不要用看似合理的要求填补空白。
• 不要添加工单套话。 不要为了让问题看起来完整而添加标题。没有最低长度要求，除开头的通俗说明段落外，也没有必需的模板。
• 不要臆造要求。 不要推断验收标准、用户故事、用户角色、范围、非目标、边缘情况、测试、发布、迁移、遥测、安全或运营要求。
• 不要臆造规划元数据。 不要推断优先级、估算、截止日期、标签、父项、依赖项、负责人、子任务或检查清单。
• 不要敲定解决方案。 不要臆造架构、API、数据模型、UI 或实现步骤。如果用户提出了某个解决方案，应将其作为有归属的背景或约束保留，不要扩展为既定设计。
• 仅在必要时澄清。 只有在不澄清就创建问题会实质性误述问题时，才提出简洁的问题。否则，创建最精简且忠实的问题，并对真正未知的事项保持开放。
• 优先使用现有问题。 条件允许时，检查是否存在可能的重复项；重用现有问题并做最少修正，而不是创建并行工单。

仅当用户明确提供或同意，或忠实转述引用材料时，才添加验收标准、规划元数据或解决方案细节。应说明来源或决策，并且不要进一步发挥。

错误报告中陈述的预期行为属于问题描述；不要将其重复生成验收标准。开始处理问题也不代表可以将其改写为解决方案规格——应将实现提案放在最终负责人的计划或讨论中。

创建或更新问题之前，删除每一句无法追溯到请求、引用证据、直接观察或明确用户决策的内容。

拉取请求交接

开始实现后，问题仍是权威的问题陈述。不要将其改写成事后解决方案规格，也不要在拉取请求描述中重复其内容。

而应在拉取请求顶部，使用实际适用的关联关系链接到问题：

- **Closes:** [PROJECT-123 Problem title](https://linear.app/example/issue/PROJECT-123/problem-title)

仅当 PR 完全解决问题时使用 Closes；仅完成部分时使用 Advances；用于背景关联时使用 Related；适合中性链接时使用 Issue。PR 后续的 In plain terms 段落只描述该 PR 为人们带来的变化，包括任何重要取舍；问题背景由关联的问题提供。

CLI 配置

CLI 命令要求设置 LINEAR_ISSUE_SORT：

export LINEAR_ISSUE_SORT=priority

否则，大多数命令都会失败。

团队

使用 linear team list 发现可用团队。

问题状态

状态	描述
triage	需要分诊的新问题
backlog	已确定优先级但尚未开始
unstarted	已准备开始（待办）
started	进行中
completed	已完成
canceled	已取消／不予处理

常用命令

列出问题

# Active issues (excludes completed/canceled)
LINEAR_ISSUE_SORT=priority linear issue list --team WDY --no-pager

# Filter by state
LINEAR_ISSUE_SORT=priority linear issue list --team WDY --no-pager -s started -s unstarted

# All issues including completed/canceled
LINEAR_ISSUE_SORT=priority linear issue list --team WDY --no-pager --all-states

查看问题

LINEAR_ISSUE_SORT=priority linear issue view WDY-123 --no-pager

更新问题状态

linear issue update WDY-123 --state "Done"
linear issue update WDY-123 --state "In Progress"

创建关联问题的 PR

linear issue pr WDY-123

列出团队

linear team list

工作流

检查要关闭的问题

# List active issues
LINEAR_ISSUE_SORT=priority linear issue list --team WDY --no-pager -s started -s unstarted -s backlog

# Cross-reference with recent commits
git log --oneline -30 --all

分诊新问题

# View issues in triage
LINEAR_ISSUE_SORT=priority linear issue list --team WDY --no-pager -s triage