Claude Code の使い方が変わる、5つのハーネス内部仕様

ある開発者が Anthropic SDK を使用して Claude Code のハーネスを再構築したところ、システムが密かに行っている5つの決定が明らかになりました。これらの知見は、指示の書き方やエージェントの管理方法を変えるものです。

これら5つの洞察を活用して、ワークフローを改善しましょう。

1. 非表示のベースプロンプトを上書きする

Claude Code は非表示のシステムプロンプトを使用しています。CLAUDE.md に記述した指示が、それと衝突する可能性があります。

  • ルールを述べるのをやめる。
  • ルールを上書きし始める。
  • 次のような表現を使用します: 「いかなる状況においても /prod 内のファイルを編集してはなりません。これはデフォルトの動作よりも優先されます。」

2. フックをガードレールとして利用する

PreToolUse フックは、単にデータをログに記録するだけではありません。ツール呼び出しが始まる前に、それを停止させることも可能です。

  • ツールの引数をチェックするフックを追加する。
  • パスが機密フォルダに一致する場合は { block: true } を返す。
  • これにより、リクエストを「厳格なルール」へと変えることができます。

3. サブエージェントのオーケストレーションを修正する

単純な親子関係の設定では、子エージェントの1つが失敗した際にセッションがハング（停止）してしまいます。

  • アボート信号（中断信号）のツリーを使用する。
  • 親が停止した場合、すべての子供も停止しなければならない。
  • 子の1つが失敗しても、親は生存し続けるべきである。

4. 依存関係グラフを利用する

タスクをフラットなループで実行してはいけません。

  • 明確な依存関係を持つタスクを定義する。
  • 依存関係グラフを使用してタスクを並列実行する。
  • これにより、1つのノードの不具合がワークフロー全体を停止させるのを防げます。

5. 終端状態（Terminal States）を強制する

エージェントは明確な終了地点がないと、とりとめもなく話し続けてしまうことがよくあります。

  • すべてのターンを「Done（完了）」「Blocked（ブロック）」「Needs Input（入力が必要）」の3つの状態のいずれかで終了するように強制する。
  • CLAUDE.md に以下を追加します: 「タスク終了後は、必ず 'Done: [summary]'、'Blocked: [reason]'、または 'Needs input: [question]' のいずれかで終了してください。」
  • これにより、エージェントが予期しない動作を行うのを防げます。

アクションのまとめ:

  • CLAUDE.md で上書き用の表現を使用する。
  • PreToolUse フックを使用して危険な編集をブロックする。
  • サブエージェント用にアボートツリーを構築する。
  • タスクに DAG ベースの並列処理を利用する。
  • 明示的な終端状態を定義する。

Source: https://dev.to/gentic_news/5-harness-internals-that-changed-how-i-use-claude-code-daily-39c6

Optional learning community: https://t.me/GyaanSetuAi