Linear Core Workflow B: プロジェクト & サイクル

概要

Linear API を使用してプロジェクト、サイクル（スプリント）、ロードマップを管理します。

前提条件

• Linear SDK の設定完了
• Linear のプロジェクト階層の理解
• プロジェクト権限を持つチームアクセス

手順

ステップ 1: プロジェクト管理

import { LinearClient } from "@linear/sdk";

const client = new LinearClient({ apiKey: process.env.LINEAR_API_KEY });

// すべてのプロジェクトを一覧表示
async function getProjects(teamKey?: string) {
  const filter = teamKey
    ? { accessibleTeams: { some: { key: { eq: teamKey } } } }
    : undefined;

  const projects = await client.projects({ filter });
  return projects.nodes;
}

// プロジェクトを作成
async function createProject(options: {
  name: string;
  description?: string;
  teamIds: string[];
  targetDate?: Date;
  state?: "planned" | "started" | "paused" | "completed" | "canceled";
}) {
  const result = await client.createProject({
    name: options.name,
    description: options.description,
    teamIds: options.teamIds,
    targetDate: options.targetDate?.toISOString(),
    state: options.state ?? "planned",
  });

  return result.project;
}

// プロジェクトのステータスを更新
async function updateProjectStatus(
  projectId: string,
  status: "planned" | "started" | "paused" | "completed" | "canceled"
) {
  return client.updateProject(projectId, { state: status });
}

ステップ 2: サイクル（スプリント）管理

// 現在と今後のサイクルを取得
async function getActiveCycles(teamKey: string) {
  const teams = await client.teams({ filter: { key: { eq: teamKey } } });
  const team = teams.nodes[0];

  const now = new Date().toISOString();
  const cycles = await team.cycles({
    filter: {
      or: [
        { endsAt: { gte: now } }, // 現在または将来
        { startsAt: { gte: now } }, // 将来
      ],
    },
    orderBy: "startsAt",
  });

  return cycles.nodes;
}

// 新しいサイクルを作成
async function createCycle(options: {
  teamId: string;
  name?: string;
  startsAt: Date;
  endsAt: Date;
}) {
  const result = await client.createCycle({
    teamId: options.teamId,
    name: options.name,
    startsAt: options.startsAt.toISOString(),
    endsAt: options.endsAt.toISOString(),
  });

  return result.cycle;
}

// サイクルにイシューを追加
async function addIssuesToCycle(issueIds: string[], cycleId: string) {
  const results = await Promise.all(
    issueIds.map(issueId =>
      client.updateIssue(issueId, { cycleId })
    )
  );

  return results.filter(r => r.success).length;
}

// サイクルのメトリクスを取得
async function getCycleMetrics(cycleId: string) {
  const cycle = await client.cycle(cycleId);
  const issues = await cycle.issues();

  const states = new Map<string, number>();
  let totalEstimate = 0;
  let completedEstimate = 0;

  for (const issue of issues.nodes) {
    const state = await issue.state;
    const stateName = state?.name ?? "Unknown";
    states.set(stateName, (states.get(stateName) ?? 0) + 1);

    totalEstimate += issue.estimate ?? 0;
    if (state?.type === "completed") {
      completedEstimate += issue.estimate ?? 0;
    }
  }

  return {
    totalIssues: issues.nodes.length,
    byState: Object.fromEntries(states),
    totalEstimate,
    completedEstimate,
    completionRate: totalEstimate ? completedEstimate / totalEstimate : 0,
  };
}

ステップ 3: ロードマップ操作

// ロードマップアイテムを取得（マイルストーン付きプロジェクト）
async function getRoadmap(options?: {
  includeCompleted?: boolean;
  monthsAhead?: number;
}) {
  const futureDate = new Date();
  futureDate.setMonth(futureDate.getMonth() + (options?.monthsAhead ?? 6));

  const filter: Record<string, unknown> = {
    targetDate: { lte: futureDate.toISOString() },
  };

  if (!options?.includeCompleted) {
    filter.state = { neq: "completed" };
  }

  const projects = await client.projects({
    filter,
    orderBy: "targetDate",
  });

  return projects.nodes.map(p => ({
    id: p.id,
    name: p.name,
    state: p.state,
    targetDate: p.targetDate,
    progress: p.progress,
  }));
}

// プロジェクトマイルストーンを作成
async function createMilestone(options: {
  projectId: string;
  name: string;
  targetDate: Date;
}) {
  return client.createProjectMilestone({
    projectId: options.projectId,
    name: options.name,
    targetDate: options.targetDate.toISOString(),
  });
}

ステップ 4: 計画ユーティリティ

// 未完了のイシューを次のサイクルに移行
async function rolloverCycle(fromCycleId: string, toCycleId: string) {
  const fromCycle = await client.cycle(fromCycleId);
  const issues = await fromCycle.issues({
    filter: {
      state: { type: { nin: ["completed", "canceled"] } },
    },
  });

  const movedCount = await addIssuesToCycle(
    issues.nodes.map(i => i.id),
    toCycleId
  );

  return { movedCount, totalUnfinished: issues.nodes.length };
}

// チームのベロシティを計算
async function calculateVelocity(teamKey: string, cycleCount = 3) {
  const teams = await client.teams({ filter: { key: { eq: teamKey } } });
  const team = teams.nodes[0];

  const cycles = await team.cycles({
    filter: {
      completedAt: { neq: null }
    },
    orderBy: "completedAt",
    first: cycleCount,
  });

  const velocities = await Promise.all(
    cycles.nodes.map(async cycle => {
      const issues = await cycle.issues({
        filter: { state: { type: { eq: "completed" } } },
      });
      return issues.nodes.reduce((sum, i) => sum + (i.estimate ?? 0), 0);
    })
  );

  const avgVelocity = velocities.reduce((a, b) => a + b, 0) / velocities.length;

  return {
    velocities,
    average: Math.round(avgVelocity * 10) / 10,
  };
}

出力

• プロジェクト CRUD 操作
• サイクル計画と管理
• ロードマップの可視化データ
• スプリント移行自動化
• ベロシティ計算

エラーハンドリング

エラー	原因	解決策
Project not found	無効なプロジェクト ID	プロジェクトが存在するか確認してください
Cycle overlap	日付が既存サイクルと重複	既存サイクルを確認してください
Permission denied	プロジェクトへのアクセス権がない	チームメンバーシップを確認してください
Invalid date range	終了日が開始日より前	日付の順序を検証してください

例

スプリント計画フロー

async function setupSprint(options: {
  teamKey: string;
  name: string;
  durationDays: number;
  issueIdentifiers: string[];
}) {
  const teams = await client.teams({ filter: { key: { eq: options.teamKey } } });
  const team = teams.nodes[0];

  const startsAt = new Date();
  const endsAt = new Date();
  endsAt.setDate(endsAt.getDate() + options.durationDays);

  // サイクルを作成
  const cycleResult = await client.createCycle({
    teamId: team.id,
    name: options.name,
    startsAt: startsAt.toISOString(),
    endsAt: endsAt.toISOString(),
  });

  const cycle = await cycleResult.cycle;

  // イシューを追加
  for (const identifier of options.issueIdentifiers) {
    const issue = await client.issue(identifier);
    await client.updateIssue(issue.id, { cycleId: cycle!.id });
  }

  return cycle;
}

リソース

• Project Object Reference
• Cycle Object Reference
• Linear Roadmaps

次のステップ

linear-common-errors を使用してエラーを効果的に処理してください。