無人エージェントの挙動変更を、フィーチャーフラグで少しずつ試す設計

import { createHash } from "node:crypto";
 
// 実行キー + フラグキー から 0..99 の安定したバケットを得る
function bucketOf(runKey: string, flagKey: string): number {
  const h = createHash("sha256").update(`${flagKey}:${runKey}`).digest();
  // 先頭2バイトを 0..99 へ写像（分布は十分に一様）
  return ((h[0] << 8) | h[1]) % 100;
}
 
type Flag = {
  enabled: boolean;
  rollout: number;
  killed: boolean;
  scope?: string[];
  owner?: string;
  createdAt?: string;
};
 
// 新挙動を割り当てるべきか。副作用なし・完全に決定論的
export function isCanary(
  flag: Flag | undefined,
  runKey: string,
  flagKey: string,
  siteScope: string,
): boolean {
  if (!flag || !flag.enabled) return false;       // 未定義・無効は旧挙動
  if (flag.killed) return false;                   // 緊急停止が最優先
  if (flag.scope?.length && !flag.scope.includes(siteScope)) return false;
  return bucketOf(runKey, flagKey) < flag.rollout; // 25 なら 0..24 が canary
}

import Anthropic from "@anthropic-ai/sdk";
 
const client = new Anthropic({ apiKey: process.env.ANTHROPIC_API_KEY });
 
const INTRO_CONTROL =
  "記事は、読者が直面している具体的な課題の描写から書き始めてください。";
const INTRO_CANARY =
  "記事は、著者自身がその課題に出会った瞬間の場面から、静かな一人称で書き始めてください。";
 
export async function generateArticle(opts: {
  runKey: string;      // 例: "claudelab/agent-feature-flag-rollout"
  site: string;        // 例: "claudelab"
  flags: Record<string, Flag>;
  topic: string;
}) {
  const useCanary = isCanary(
    opts.flags["gentler-intro-phrasing"],
    opts.runKey,
    "gentler-intro-phrasing",
    opts.site,
  );
  const variant = useCanary ? "canary" : "control";
  const introRule = useCanary ? INTRO_CANARY : INTRO_CONTROL;
 
  const msg = await client.messages.create({
    model: "claude-sonnet-5",
    max_tokens: 4096,
    system: `あなたは技術記事の執筆者です。\n${introRule}`,
    messages: [{ role: "user", content: opts.topic }],
  });
 
  // どちらの群で生成したかを必ず記録する（後の比較の生命線）
  return { variant, text: msg.content, runKey: opts.runKey };
}

type RunLog = {
  runKey: string;
  variant: "control" | "canary";
  gatePassed: boolean;   // 品質ゲートを一度で通ったか
  charCount: number;     // 生成本文の文字数
  ts: string;
};
 
// 直近ログから両群の通過率を出す
function compare(logs: RunLog[]) {
  const rate = (v: string) => {
    const g = logs.filter((l) => l.variant === v);
    const pass = g.filter((l) => l.gatePassed).length;
    return { n: g.length, passRate: g.length ? pass / g.length : 1 };
  };
  return { control: rate("control"), canary: rate("canary") };
}

import { readFileSync, writeFileSync } from "node:fs";
 
// canary が control より REGRESSION_PT 以上低ければ kill する
const REGRESSION_PT = 0.05; // 5ポイント
const MIN_CANARY = 3;       // 最低サンプル数
 
export function autoRollback(flagKey: string, logs: RunLog[], path: string) {
  const { control, canary } = compare(logs);
  if (canary.n < MIN_CANARY) return { acted: false, reason: "サンプル不足" };
 
  const gap = control.passRate - canary.passRate;
  if (gap < REGRESSION_PT) return { acted: false, reason: "回帰なし" };
 
  const flags = JSON.parse(readFileSync(path, "utf8"));
  flags[flagKey].killed = true;
  flags[flagKey].killedAt = new Date().toISOString();
  flags[flagKey].killedReason =
    `canary passRate ${canary.passRate.toFixed(2)} < control ${control.passRate.toFixed(2)}`;
  writeFileSync(path, JSON.stringify(flags, null, 2));
  return { acted: true, gap };
}