ローカルコーディングエージェントの作業ハーネス設計例

Node.jsを導入した練習フォルダーでsrc/label.mjsとtest/label.test.mjsを作ります。関数は前後の空白を削除しますが、空白だけを入力すると空文字列を返します。要件は空の名前にUntitledを使うことです。

export function normalizeLabel(text) {
  return text.trim();
}

import test from 'node:test';
import assert from 'node:assert/strict';
import { normalizeLabel } from '../src/label.mjs';

test('trims ordinary names', () => {
  assert.equal(normalizeLabel('  Project  '), 'Project');
});
test('replaces an empty name', () => {
  assert.equal(normalizeLabel('   '), 'Untitled');
});

先に実行すると通常の文字列は合格し、空の名前は失敗します。この失敗と期待する戻り値をエージェントに渡します。広い改善依頼より、何を直せば完了か明確になります。

node --test test/label.test.mjs

指示には変更してよいファイルとテストを記します。例はAGENTS.mdを読むエージェント向けです。別のファイルを読む製品ではそこに同じ内容を入れ、編集前に適用した指示と対象ファイルを説明させます。

編集対象: src/label.mjs
要件: 空白削除後が空ならUntitledを返す
検証: node --test test/label.test.mjs
テストは変更しない
ネットワーク、デプロイ、秘密ファイル閲覧は禁止
報告: 変更ファイル、テストと結果、残る問題

指示に合わせて実行権限も設定します。この練習に必要なのはファイルの読み取り、関数の編集、テストを実行するターミナルです。ネットワークとデプロイは不要なので許可リスト¹から外します。

src/label.mjsだけを編集して空の名前のテストを通すよう依頼し、同じテストを再実行します。この例では空白削除後が空のときだけUntitledを返せば両方が合格します。

export function normalizeLabel(text) {
  const label = text.trim();
  return label || 'Untitled';
}

最後に関数とテストを並べて読みます。戻り値の代わりに期待値を変えていないか、無関係なファイルを変更していないか確認します。失敗が続く場合は全体を書き直させず、入力とこの関数のdiffを調べます。

実際のリポジトリでも再現入力、対象ファイルとテスト、結果確認の順を保ちます。削除、デプロイ、外部送信は必要時に別途承認し、復旧も今回の変更だけを対象にして他の作業者の変更を保護します。