GPT-6 Astra時代のコンテキスト剪定入門——SkillsとAGENTS.mdを軽くする

はじめに

AIコーディングエージェントを長く使っていると、リポジトリ内の指示がだんだん増えていきます。

2026年9月11日、OpenAI Developersは「Rethinking skills and prompts for GPT-6 Astra」を公開しました。要点は、GPT-6 Astraのような高性能モデルでは、過去に必要だった細かい足場かけをそのまま残すと、コンテキストを圧迫し、作業を遅くし、不要な慎重さを生むことがある、という話です。

また、OpenAI APIのモデルガイドでは、GPT-6 Astraはソフトウェアエンジニアリングや複数ステップの作業に強く、Responses APIでは model に gpt-6-astra を指定すると説明されています。加えて、async tool calling、mid-turn steering、reasoning effortの途中変更なども新しい要素として挙げられています。

本記事では、架空の問い合わせ管理SaaS「HelpDeskHub」を題材に、Next.js + Firestore + GitHub Actionsで、SkillsとAGENTS.mdを継続的に棚卸しする仕組みを作ります。

参考にした一次情報は次の通りです。

• Rethinking skills and prompts for GPT-6 Astra
• OpenAI API Model guidance: Using GPT-6 Astra

何を変えるべきか

今回のテーマは「AI向けの指示をもっと増やす」ではありません。むしろ、指示の読み込み条件を明確にして、不要なものを削ることです。

OpenAI Developersの記事では、スキル説明は短く、いつ使うべきかが分かる形にすること、複数ワークフローを持つスキルはルート文書を薄いルーターにすること、AGENTS.mdでは全タスクに毎回読む資料を積まないことが勧められています。

HelpDeskHubでは、次の3種類に分けて整理します。

ハンズオン1: AGENTS.mdを条件付きルーターにする

まず、肥大化したAGENTS.mdを短くします。全部を削るのではなく、いつ読むかを決めます。

# AGENTS.md

## Project

HelpDeskHub is a Next.js App Router application using TypeScript,
Tailwind CSS, Firebase Authentication, and Firestore.

## Default Rules

- Prefer Server Components unless client state or browser APIs are required.
- Keep Firestore writes behind Server Actions or trusted server routes.
- Run `yarn build` before publishing user-facing changes.
- Do not use real customer names, tickets, or production data in examples.

## Read When Needed

- Use `docs/ai/firestore-model.md` when changing collections, indexes, or security rules.
- Use `docs/ai/release-flow.md` when editing GitHub Actions or deployment behavior.
- Use `docs/ai/ui-patterns.md` when adding dashboard screens.

ポイントは、docs/ai/firestore-model.md を「必ず最初に読む」と書かないことです。タイポ修正や文言変更では不要だからです。モデルに全部読ませるのではなく、作業内容に応じて探せる地図を渡します。

ハンズオン2: 指示ファイルをFirestoreに棚卸しする

次に、AI向け指示のメタ情報をFirestoreへ保存します。目的は、長すぎる指示、曖昧なトリガー、古いモデル名を見つけることです。

// scripts/audit-ai-instructions.mjs
import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
import { join } from "node:path";
import { FieldValue, getFirestore } from "firebase-admin/firestore";

function collectMarkdownFiles(dir) {
  if (!existsSync(dir)) return [];

  return readdirSync(dir).flatMap((entry) => {
    const path = join(dir, entry);
    const stat = statSync(path);

    if (stat.isDirectory()) {
      return collectMarkdownFiles(path);
    }

    return path.endsWith(".md") ? [path] : [];
  });
}

function inspectFile(path) {
  const text = readFileSync(path, "utf8");
  const lines = text.split("\n");

  return {
    path,
    lineCount: lines.length,
    charCount: text.length,
    hasAlwaysRead: /always read|必ず.*読む|毎回.*読む/i.test(text),
    mentionsModel: /gpt-5|gpt-6|astra|sonnet|opus|codex/i.test(text),
  };
}

export async function saveInstructionAudit() {
  const db = getFirestore();
  const files = [
    "AGENTS.md",
    ...collectMarkdownFiles("docs/ai"),
    ...collectMarkdownFiles(".codex/skills").filter((path) =>
      path.endsWith("SKILL.md"),
    ),
  ].filter((path) => existsSync(path));

  const records = files.map(inspectFile);
  const auditRef = db.collection("aiInstructionAudits").doc();

  await auditRef.set({
    createdAt: FieldValue.serverTimestamp(),
    records,
    summary: {
      fileCount: records.length,
      longFileCount: records.filter((record) => record.lineCount > 120).length,
      alwaysReadCount: records.filter((record) => record.hasAlwaysRead).length,
      modelMentionCount: records.filter((record) => record.mentionsModel).length,
    },
  });
}

このスクリプトは、公式に存在しないCLIやAPIに依存しません。Node.jsの標準ライブラリとFirebase Admin SDKだけで、指示ファイルの状態を記録します。

ハンズオン3: Next.jsで監査結果を見る

保存した監査結果は、管理画面で見えるようにします。まずは最新1件を読むServer Componentを作ります。

// src/app/admin/ai-instructions/page.tsx
import { getFirestore } from "firebase-admin/firestore";

type AuditSummary = {
  fileCount: number;
  longFileCount: number;
  alwaysReadCount: number;
  modelMentionCount: number;
};

async function getLatestAudit(): Promise<AuditSummary | null> {
  const snapshot = await getFirestore()
    .collection("aiInstructionAudits")
    .orderBy("createdAt", "desc")
    .limit(1)
    .get();

  const doc = snapshot.docs.at(0);
  return doc?.data().summary as AuditSummary | null;
}

export default async function AiInstructionsPage() {
  const summary = await getLatestAudit();

  if (!summary) {
    return <p className="text-sm text-slate-500">No audit result yet.</p>;
  }

  return (
    <main className="space-y-6">
      <h1 className="text-2xl font-semibold">AI Instruction Audit</h1>
      <dl className="grid gap-4 md:grid-cols-4">
        <Metric label="Files" value={summary.fileCount} />
        <Metric label="Long files" value={summary.longFileCount} />
        <Metric label="Always-read hints" value={summary.alwaysReadCount} />
        <Metric label="Model mentions" value={summary.modelMentionCount} />
      </dl>
    </main>
  );
}

function Metric({ label, value }: { label: string; value: number }) {
  return (
    <div className="rounded border border-slate-200 p-4">
      <dt className="text-sm text-slate-500">{label}</dt>
      <dd className="mt-2 text-3xl font-semibold">{value}</dd>
    </div>
  );
}

modelMentionCount は悪ではありません。ただし、特定モデル向けに書いた指示は、モデル更新時に棚卸し対象になります。今回のOpenAI Developersの記事がまさにその例で、GPT-6 Astraへ切り替えるなら、GPT-5.6 Sol時代の過剰な補助線を見直す価値があります。

ハンズオン4: GitHub Actionsで週次チェックする

最後に、毎週月曜に監査を走らせます。GitHub ActionsのcronはUTCなので、JSTの月曜朝9時なら日曜深夜の 0 0 * * 1 です。

name: Audit AI Instructions

on:
  schedule:
    - cron: "0 0 * * 1"
  workflow_dispatch:

jobs:
  audit:
    runs-on: ubuntu-latest
    timeout-minutes: 10
    permissions:
      contents: read
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: "22"
          cache: "yarn"
      - run: yarn install --frozen-lockfile
      - name: Run instruction audit
        env:
          FIREBASE_SERVICE_ACCOUNT_JSON: ${{ secrets.FIREBASE_SERVICE_ACCOUNT_JSON }}
        run: node scripts/audit-ai-instructions.mjs

運用では、いきなり失敗条件を厳しくしすぎないのがおすすめです。まずはFirestoreに記録し、2〜3週間分の推移を見てから、「120行を超えるSKILL.mdはレビュー対象」「必ず読む が増えたらIssueを立てる」のようにチームの基準へ落とします。

Astra向けプロンプトの書き方

GPT-6 Astraの公式ガイドでは、曖昧な部分を文脈で補い、結果に影響する場合は絞った質問をし、途中の要件変更にも追従しやすいことが説明されています。だからこそ、プロンプト側では「全部先回りして縛る」より、「完了条件」と「判断境界」を明確にします。

OpenAI APIでAstraを直接使う場合は、公式ガイドにある通りResponses APIの model に gpt-6-astra を指定します。ただし、この記事の監査フロー自体は特定APIに依存しません。まずはリポジトリの指示を軽くするだけでも、Codexや他のエージェントに渡る文脈はかなり整います。

まとめ

GPT-6 Astra時代のAI開発では、「指示を増やす力」だけでなく「指示を剪定する力」が重要になります。

• Skillsの説明は短く、いつ使うかを明確にする
• AGENTS.mdは全ファイルを毎回読ませる場所ではなく、条件付きの地図にする
• 過去モデル向けの過剰な手順や停止条件は、モデル更新時に見直す
• Next.js + Firestore + GitHub Actionsで、AI向け指示の棚卸しを継続運用にする

AIエージェントの精度は、モデル性能だけで決まりません。リポジトリが渡すコンテキストの鮮度と軽さも、同じくらい効きます。次に大きな機能を任せる前に、まずは AGENTS.md とSkillsを一度剪定してみてください。

参考資料

• Rethinking skills and prompts for GPT-6 Astra
• OpenAI API Model guidance: Using GPT-6 Astra
• Unsplash photo by Markus Spiske