公式の利用ガイドでは、dshは起動元ディレクトリを基準に扱い、Web UIではワークスペースを選択して作業対象を定めます。つまり、ファイルが存在していても、DeepSeek HarnessでAGENTS.mdが効かない場合は、まず会話の作業場所とプロジェクトルートを固定し、その後に候補ファイル、容量、上書き層、会話の更新状態を確認するのが最短です。ファイルを長くすることは最後まで避けてください。(公式Web UIガイド)
すでにAGENTS.mdを作成したのに規約が無視される開発者、monorepoや多層ディレクトリを管理する技術責任者、ローカル環境をリモートMacへ移して挙動が変わった運用担当者が対象です。単一プロジェクトで毎回同じ場所から起動している場合は、候補ファイルと会話更新の確認だけで解決できる可能性があります。
失敗例から見る、最初に疑うべき境界
典型的な失敗は、リポジトリ直下にAGENTS.mdを置き、独自ルールを追加したのに、新しく作ったつもりの会話でもAgentが従わないケースです。ここで「内容をもっと強く書く」「冒頭に禁止事項を増やす」と進めると、実際には別のディレクトリを見ている問題や、古い会話のコンテキストを調べないまま時間を使うことになります。
DeepSeek Harnessの公式リポジトリ自身も、ルートのAGENTS.mdを開発時の指示として使用しています。ただし、公式リポジトリ内の構成が、あなたのプロジェクトで同じ優先順位や候補順になるとは限りません。別のエージェント製品で知られている動作を、そのままDeepSeek Harnessの仕様として扱わないでください。(公式AGENTS.md)
注意：候補ファイルの既定順、変更監視の有無、画面上の読み込み表示は、利用中の版によって変わる可能性があります。確認できない挙動は、推測ではなく最小リポジトリで再現してください。
会話作成前に作業場所を固定する
最初に、ターミナルとWeb UIの「プロジェクト」が同じ場所を指しているか確認します。会話を作る前に、次の情報を記録してください。
pwdまたは同等の方法で確認したdshの起動ディレクトリ- Web UIで選択したワークスペースの絶対パス
git rev-parse --show-toplevelで確認した実際のリポジトリルート- ルート判定に使う設定やプロジェクトルート標識の有無
AGENTS.md、CLAUDE.md、ローカル上書きファイルの絶対パス
git rev-parse --show-toplevelは、現在の作業ツリーの最上位ディレクトリを表示するための公式コマンドです。(Git公式リファレンス) 起動場所とWeb UIで選択したワークスペースが異なる場合、ファイルの存在確認は成功しても、Agentが組み立てるworkspace contextは別物になる可能性があります。最初から同じ絶対パスを使い、相対パスだけで判断しないことが重要です。
その後、業務コードを含まない最小テスト用リポジトリを作ります。ルートに短いAGENTS.mdだけを置き、「最初の応答にRULE-CHECK-ALPHAの確認結果を含める」といった、他の文書にはない無害な規則を1つ入れてください。最小リポジトリで反応しないなら、アプリケーションの複雑さではなく、読み込み経路の問題です。
初回読み込みで候補ファイルを証明する
次は、ファイルがあるかではなく、モデルに渡されたかを確認します。候補を次の層に分け、実際の場所と順序を記録してください。
- ユーザー全体に適用する指示
- プロジェクトルートの指示
- 現在のサブディレクトリに置いた指示
.local系など、端末だけで使う上書き- Web UIや起動オプションで指定した追加コンテキスト
この段階で「AGENTS.mdがあるので自動で読まれる」と決めつけないでください。公式リポジトリのルートにはAGENTS.mdが置かれていますが、これはファイルの存在を示す材料であって、すべてのプロジェクトでの自動認識や優先順位を保証するものではありません。
検証用の指示は、実ファイルの中身を逐語的に答えさせる必要はありません。「最初の応答にRULE-CHECK-ALPHAの確認結果を含める」というルールを入れ、読み取り専用の質問を送ります。応答に固有語がない場合は、ルールが弱いのではなく、候補から外れた、別ファイルが選ばれた、内容予算に収まらなかった、または会話へ追加されていない可能性を順に調べます。
CLAUDE.mdも同じ位置に置いている場合は、両方が存在することだけで優先順位を判断しないでください。DeepSeek Harnessの当日版設定とソースで確認できないなら、同じ規則を二重管理せず、基準ファイルを1つに決める方が安全です。もう一方は参照資料または移行用メモに整理し、競合したときにどちらを直すのかを明確にします。
サブディレクトリとworkspace contextの差分を取る
monorepoでは、リポジトリルートから起動した会話と、対象パッケージのディレクトリから起動した会話を分けて比較します。両方で同じ基準タスクを実行し、Agentが認識したプロジェクト名、確認すべきテストコマンド、検証用固有語を保存してください。
差分が出たときは、次の3つを分けて考えます。
- ルートの指示だけが入っている
- サブディレクトリ側の指示が追加されている
- パスのずれにより、別プロジェクトの指示を拾っている
同じ内容をルートと子ディレクトリへコピーすると、重複が折り畳まれたり、どの規則が有効なのか説明しにくくなったりします。共通方針はルート、パッケージ固有の実行方法は対象ディレクトリというように責務を分け、各ファイルに適用範囲を書いてください。
DeepSeek Harnessはプラグイン構成とコンテキスト関連の拡張点を持つ設計として公開されていますが、拡張点があることは、すべてのMarkdownファイルが同じ扱いを受けることを意味しません。ファイル名と配置を増やすより、どの会話でどの指示集合が使われたかを比較できる状態にする方が、保守上の価値があります。(公式アーキテクチャ文書)
容量と形式の問題を切り分ける
指示ファイルが長い場合、固定の文字数上限やトークン数を推測しないでください。利用中の版、追加されたworkspace context、会話履歴によって、実際に利用できる余地は変わるためです。確認すべきなのは、文字コード、改行、読み取り権限、実効サイズ、他のコンテキストを含めた全体量です。
まずは次の順で縮小します。
- 背景説明、設計資料、長いFAQを別ファイルへ移します。
- AGENTS.mdには実行制約、確認コマンド、禁止事項だけを残します。
- 見出しと箇条書きを使い、同じ規則の重複を削ります。
- 検証用の固有語を残したまま、新規会話を作ります。
- 短縮後に固有語が応答へ出るか比較します。
Macではfile AGENTS.md、wc -c AGENTS.md、sed -n '1,80p' AGENTS.mdなどで形式とサイズを確認できます。公式版で具体的な既定上限が明示されていないなら、「何KBまで」と断定せず、短縮前後の挙動を記録して判断します。
経験則：実行規約と説明資料を1つの巨大なファイルに詰め込むより、短い基準ファイルから必要な資料を参照させる方が、どの規則が入ったかを検証しやすくなります。
ファイル変更後は会話を分けて確認する
AGENTS.mdを編集したのに旧ルールが残る場合、ファイル監視の故障とは限りません。会話履歴が以前の内容を保持しているだけかもしれないため、同じ基準タスクを次の3条件で実行します。
- 変更前から続けている旧会話
- ファイル変更後に作った新規会話
- dshの実行プロセスを再起動してから作った新規会話
各結果には、実行日時、起動場所、ファイルの変更差分、検証用固有語、Agentの応答を残します。新規会話だけが新ルールに従うなら、ファイル監視ではなく会話コンテキストの保持が原因です。再起動後だけ変わるなら、プロセス内キャッシュや初期化時の設定を疑います。
Web UIでモデル設定を保存した場合の反映方法と、指示ファイルを変更した場合の反映方法は同じとは限りません。設定画面で即時反映される項目があっても、AGENTS.mdの変更まで同じ動作をすると一般化しないでください。変更後の新規会話を基準にし、旧会話は検証対象から外す方が判定を誤りにくくなります。
リモートMacへ移した後の確認手順
ローカルからリモートMacへ移行した後は、提示文を書き換える前に環境差分を確認します。最低限、次の項目を同じ順番で記録してください。
DSH_HOMEの実効値と、セッション・設定の保存先- dshを起動したユーザーと起動ディレクトリ
- Web UIで選択したワークスペースの絶対パス
AGENTS.mdとCLAUDE.mdの所有者、読み取り権限、改行形式- プロジェクトルート標識と候補ファイルの配置
- ローカルとリモートで同じ基準タスクを実行した応答
Macの所有者やアクセス権は、ls -lやstatなどで確認できます。macOSのファイル所有権とアクセス権については、Appleのファイルシステム説明も参照してください。リモート側だけ失敗するなら、まずファイルの交付漏れ、パスの差、権限、環境変数を疑います。
逆に両方で失敗するなら、候補ファイルの仕様、内容予算、会話作成時の読み込み設定へ戻ります。どうしても切り分けられない場合は、旧セッションを廃棄し、既知のクリーンな作業ディレクトリから新規会話を作ります。リモートMacの作業形態を見直す場合は、リモートMacの活用事例を参照し、利用条件はKVMFLUXの料金案内で確認してください。
最終判定に使えるチェックリスト
- [ ] dshの起動ディレクトリを記録した
- [ ] Web UIの選択ワークスペースを記録した
- [ ]
git rev-parse --show-toplevelでプロジェクトルートを確認した - [ ] AGENTS.md、CLAUDE.md、ローカル上書きの候補を列挙した
- [ ] 候補順を設定またはソースで確認し、推測で補っていない
- [ ] 固有語を使った無害な読み込み検証を行った
- [ ] ルート会話とサブディレクトリ会話を比較した
- [ ] エンコード、読み取り権限、実効サイズを確認した
- [ ] 旧会話、新規会話、プロセス再起動後を比較した
- [ ] リモート環境の
DSH_HOME、パス、権限、基準タスクを記録した - [ ] 指示ファイルを長文化する前に、背景資料と実行規約を分離した
現在の開発環境がローカルMacや一般的なクラウド環境の場合、起動場所、権限、ワークスペース選択、セッション保存先が担当者ごとにずれやすく、再現性の確認にも手間がかかります。特に長期運用では、環境を都度作り直す負担、接続経路の差、設定ファイルの交付漏れが、AGENTS.mdの問題として誤認されがちです。
その点、KVMFLUXのMac環境を一時的な検証場所として使えば、同じプロジェクト、同じ基準タスク、同じ権限確認を切り分けやすくなります。長期の固定負荷や物理インターフェースが必要な開発には自前機が向きますが、指示読み込みの再現確認や短期の遠隔開発では、環境差を減らせるレンタルMacの方が判断を進めやすい場面があります。
よくある質問
DeepSeek HarnessはAGENTS.mdを自動で読んでくれますか？
自動読み込みを期待する前に、利用中のバージョンの設定と実際のワークスペースを確認してください。公式リポジトリにはAGENTS.mdを使う構成が存在しますが、ファイルがディスク上にあることと、現在の会話のworkspace contextへ入っていることは別です。独自の検証ルールを置き、新規会話で応答を確認するのが安全です。
AGENTS.mdはどの場所に置けば認識されますか？
まず、DeepSeek Harnessを起動したディレクトリとWeb UIで選択したワークスペースを同じプロジェクトルートにそろえてください。ルート判定や候補ファイルの設定が有効なら、その基準に従います。monorepoではルート直下だけでなく、対象サブディレクトリで別の規則が選ばれていないかを新規会話で比較します。
AGENTS.mdとCLAUDE.mdが同時にある場合はどうなりますか？
両方があるときの優先順位を、別のエージェント製品の仕様から推測してはいけません。DeepSeek Harnessの当日版設定とソースを確認し、候補順が明記されていなければ、同じ内容を二重管理せず、片方を基準ファイルにしてもう片方は参照またはリンクに整理します。重複は折り畳みや競合の判定を難しくします。
リモート環境に移した後、プロジェクト指示が読み込まれないのはなぜですか？
移行後は、リポジトリの場所だけでなく、DSH_HOME、起動ユーザー、ファイル所有者、読み取り権限、Web UIの選択状態が変わることがあります。ローカルとリモートで同じ基準タスクを実行し、起動ディレクトリ、実効パス、指示ファイルの内容、Agentの応答を保存してください。差分が見えれば、提示文の問題か環境の問題かを分離できます。
安定した専有Mac環境で、開発作業をスムーズに進めませんか
KVMFLUXなら、専有のMac mini M4を数分で用意し、SSHまたはVNCからすぐに接続できます。 起動ディレクトリやワークスペースに左右されにくい、継続利用しやすい専用のリモートmacOS環境を構築できます。 CIビルドや検証、署名作業に必要なApple Siliconの実機を、日額・週額・月額・四半期から用途に合わせて利用できます。 日本を含む6拠点から接続先を選び、必要な期間だけMacを確保して開発環境を効率化できます。