DeepSeek Harness AGENTS.md Not Taking Effect: 2026 Fix

The file AGENTS.md is present, but DeepSeek Harness behaves as if it has never seen the project rules.

Check the session working directory and detected project root first, then verify candidate files, content limits, overrides, and a fresh context before rewriting the instructions.

This guide is for developers who already created AGENTS.md but still see ignored conventions, technical leads maintaining nested rules in a monorepo, and operators whose project behavior changes after moving a workspace to a remote Mac.

The failure pattern

A common failure looks deceptively simple:

• You create AGENTS.md in the repository.
• You start DeepSeek Harness.
• The Agent follows generic behavior instead of the project rules.
• You add more explanations to the file.
• The next session still behaves the same.

The mistake is treating instruction loading as a writing problem. In most cases, the first question is not “Is the rule clear?” It is “Did this file enter the context assembled for this session?”

The public project documentation shows that the harness can read and modify files inside a workspace, persist sessions, and assemble context through a dedicated context layer. It also resolves file operations within the workspace boundary rather than treating the entire filesystem as available. Those details make path selection and session state part of the diagnosis, not secondary implementation trivia. Review the project runtime and context components and inspect the repository’s documented workspace behavior before changing production instructions.

Three hidden costs make this problem persist:

• Wrong root: the terminal, Web UI, and repository browser can point to different directories.
• Layer collision: global rules, project rules, nested files, and local overrides may be merged or filtered differently.
• Stale context: an existing session may retain the previous instruction set even after the file changes.

A fourth risk appears in remote environments: the file may exist in the copied repository while the process uses another workspace path or another DSH_HOME.

Do not use community posts to establish a default instruction priority or automatic path rule. For current behavior, compare your installed configuration with the DeepSeek Harness source tree and the context assembly implementation, then validate the result in a disposable repository.

Session start checks

The first checkpoint is the moment before creating a session. Do not begin with an ordinary business task. Use a small disposable repository so that application code, generated files, and previous conversation history cannot confuse the result.

Record these values in one note:

• The directory from which dsh or the equivalent launcher starts.
• The workspace selected in the Web UI, if you use one.
• The absolute path of the repository root.
• The path where you placed AGENTS.md.
• The active DSH_HOME, if the installation supports it.
• The DeepSeek Harness version and launch mode.

The repository root must be identified by the configuration used by your installed version. The task brief confirms that DeepSeek Harness exposes configuration for project-root markers, candidate instruction files, and context budgeting, but default candidate order and interface feedback must be checked against the version you are running. Do not convert a remembered path from another tool into a DeepSeek Harness guarantee.

Create a minimal structure:

harness-rule-test/
├── AGENTS.md
├── marker.txt
└── src/
    └── sample.txt

Put one harmless, unique rule in AGENTS.md, such as:

# Test project instructions

When asked to inspect this repository, mention the token BLUE-CEDAR
and do not edit any file unless explicitly requested.

The rule should be safe, specific, and easy to observe. Avoid instructions that depend on a particular model style, hidden reasoning, or an exact response format. Your goal is to establish whether the file was discovered, not whether the Agent can obey a complicated policy.

Use a clean launch from the intended root. Then ask the Agent to inspect the repository and report the project instructions it can use. If the response does not mention your marker, stop there. Do not add more prose to the file. The failure is still at discovery, path resolution, readability, or context assembly.

DeepSeek Harness AGENTS.md not taking effect: discovery checks

Once the working directory is known, inspect the candidate instruction set. The relevant candidates may include:

• A user-level instruction file.
• A project-level AGENTS.md.
• A project-level CLAUDE.md.
• Nested instruction files in child directories.
• A local override or environment-specific file.
• Configuration entries that enable or disable each source.

File existence is only the first observation. You need evidence for three separate states:

• Found: the loader located the file.
• Accepted: the file passed path, encoding, permission, and size checks.
• Injected: the file content entered the session context.

Use different markers in each candidate file:

AGENTS marker: BLUE-CEDAR

CLAUDE marker: GREEN-ORBIT

Local override marker: RED-PINE

Do not use conflicting operational rules yet. Conflicting rules make it impossible to tell whether the file was ignored or simply superseded. First prove which files are visible. Only then test precedence.

The project README documents an explicit file-read tool, session persistence, /clear, session listing, and resume behavior. These capabilities are useful during diagnosis because they let you separate a read failure from a stale conversation. The README also describes path traversal protection and workspace-bounded file operations, so a successful file read from one path does not prove that another path was used when the session began. Check the documented chat and session behavior.

For each candidate, capture:

• Absolute path.
• File name and capitalization.
• Ownership and read permission.
• Character encoding.
• Approximate size.
• Whether it is inside the configured project root.
• Whether the current session was created before or after the last edit.

A useful verification prompt asks the Agent to list the instruction sources it can identify and quote only the harmless marker. If the UI does not expose the assembled context, use behavior as a probe, but make the behavior low-risk and reproducible.

The recovery standard is not “the Agent eventually followed the rule.” It is stronger: the expected marker must appear in a fresh session, from the intended root, without requiring a business-specific prompt to remind the Agent about the file.

Nested workspace behavior

The next checkpoint is entering a child directory. This is where monorepos create the most misleading reports.

Suppose your repository looks like this:

company-repo/
├── AGENTS.md
├── packages/
│   ├── mobile/
│   │   └── AGENTS.md
│   └── service/
│       └── CLAUDE.md
└── tools/

A session created at company-repo/ may receive a different instruction set from a session created at company-repo/packages/mobile/. That difference can be intentional inheritance, a project-root change, or accidental path resolution. You cannot diagnose it by opening the files in a graphical editor.

Run the same baseline task from:

• The repository root.
• The relevant package directory.
• A directory below the package.
• A sibling package.

Give each file a unique marker and keep the task identical. Record the observed set in plain text:

Root session: BLUE-CEDAR
Mobile session: BLUE-CEDAR, YELLOW-LANTERN
Service session: BLUE-CEDAR, GREEN-ORBIT

Do not assume that repeated content will appear repeatedly. Loaders may fold duplicate content, normalize identical blocks, or suppress a file whose content is already represented elsewhere. A missing marker is more useful than a repeated paragraph because it tells you whether the candidate was distinguishable.

Also check path alignment. A Web UI may display a workspace label while the process runs in a mounted or translated path. A symlink can make the same repository appear under more than one absolute path. A remote mount can preserve files but change the parent-directory chain used for instruction discovery.

The recovery standard is precise: each directory must produce the expected instruction set for its intended scope, and the same harmless marker must be recognized in two consecutive fresh sessions.

File content and budget boundaries

A file can be readable and still fail to influence the session because the assembled workspace context exceeds the available budget or because the file contains formatting that the loader cannot process as expected.

The task brief deliberately does not provide a fixed DeepSeek Harness instruction-file limit. Do not publish a guessed maximum in bytes, lines, or tokens. Instead, inspect the active configuration and documentation for your version, then test a reduced file. The context module in the source repository is the appropriate place to verify how context assembly is implemented in the version you operate.

Check the following:

• The file is valid text rather than a binary or damaged export.
• The encoding is readable by the running process.
• The beginning and end of the file are intact.
• Generated notes, copied tickets, logs, and large design documents are not mixed into the core rules.
• The total workspace context leaves room for the actual task.
• Markdown headings and lists are closed cleanly.
• Instructions do not depend on an external file that is absent remotely.

Separate stable execution constraints from background material:

AGENTS.md
├── Required commands
├── Forbidden operations
├── Test and review gates
├── Source layout
└── Short escalation rules

Move architecture history, long API references, meeting notes, and examples into separate files that the Agent can load only when needed. The goal is not to make the instruction file as large as possible. The goal is to make the non-negotiable rules visible early and unambiguous.

For a controlled test, create three versions:

• A short file containing only the unique marker.
• A normal file containing the real rules.
• A reduced file with background sections removed.

If the short file works but the normal file does not, compare content length, formatting, and context pressure. If the reduced file works again, keep the concise version and move reference material out of the automatic instruction layer.

Do not use a fixed context ceiling copied from another DeepSeek client as evidence for DeepSeek Harness. Different wrappers can expose different configuration names, defaults, and accounting methods. The relevant result is the smallest file that remains reliably loaded in your own deployment.

Candidate conflicts and local overrides

After discovery is proven, test conflicts. Keep the same harmless marker method, but add one clearly different rule to each layer.

For example:

• AGENTS.md says the Agent should report BLUE-CEDAR.
• CLAUDE.md says it should report GREEN-ORBIT.
• A local override says it should report RED-PINE.

Do not claim a universal precedence order. The task brief confirms that candidate files and local overrides are configurable, while the default order and merge behavior must be verified for the current release. A media post or community example is not sufficient evidence for a DeepSeek Harness priority rule.

Run the test in a new session and preserve the response. Then remove one candidate at a time. This creates a small decision tree:

• Removing one file changes the result: that file was active.
• Removing one file changes nothing: it may be ignored, duplicated, outside scope, or masked.
• The result changes only after a new session: the old session held stale context.
• The result changes after process restart but not session creation: inspect session persistence and runtime initialization.

Keep AGENTS.md and CLAUDE.md deliberately different during the test. Once the effective layer is known, consolidate repeated rules. Duplicate policy text creates maintenance cost and makes future regressions harder to attribute.

Mid-article FAQ

Automatic loading

DeepSeek Harness can support automatic instruction discovery, but “automatic” does not mean “search every directory and use every Markdown file.” The loader works within configured roots and candidate sources. Verify the active configuration, then test a unique marker in a minimal repository. If the marker is absent, investigate path and discovery before changing the wording.

Correct placement

Place project rules where the active project-root configuration says the loader will search. In a layered repository, do not rely on the editor’s displayed folder name. Compare the absolute launch directory, detected root, and file path. A root marker can prevent the process from continuing into an unrelated parent project, but its exact behavior must be confirmed in your installed version.

AGENTS.md and CLAUDE.md together

Treat both files as separate candidates until verified. They may be merged, filtered, or selected according to configuration. Duplicate copies of the same rule make testing harder because the loader may fold them. Use distinct markers first, then consolidate stable rules after you know which source is active.

Remote instruction loading

A remote restart can change the process directory, workspace mount, environment home, permissions, or session database. Compare local and remote runs against the same disposable repository. If the local marker appears but the remote marker does not, inspect delivery and environment parity before modifying project instructions.

File edits and session refresh

The next checkpoint is after changing a rule. A file watcher failure is only one possible explanation. The current session may simply contain the old context.

Run three tests in this order:

• Continue the old session and ask whether the updated marker is recognized.
• Create a new session in the same workspace.
• Restart the DeepSeek Harness process, then create another new session.

Save the before-and-after evidence:

Before edit: marker BLUE-CEDAR recognized
File edit: marker changed to SILVER-ROBIN
Old session: BLUE-CEDAR
New session: SILVER-ROBIN
After process restart: SILVER-ROBIN

This result points to stale session context rather than a broken file watcher. If the new session still shows the old marker, recheck the path and candidate file. If the process restart changes the behavior, inspect how session state and configuration are initialized.

The documented interface includes session persistence and a transcript-clearing command, but clearing visible conversation is not automatically the same as rebuilding every runtime context source. Test a genuinely new session when you need to prove that the instruction loader ran again. Review the documented session commands.

Do not use a continued conversation to approve a configuration change. A session can answer correctly because the earlier messages mentioned the rule, even when the edited file was never loaded. Only a new session, with a fresh marker and the same baseline task, can separate file discovery from conversational memory.

Remote recovery sequence

After migration or remote restart, use this order rather than editing prompts repeatedly:

• [ ] Print the absolute working directory used by the launcher.
• [ ] Confirm the Web UI workspace maps to the intended repository path.
• [ ] Resolve the project root using the configured marker.
• [ ] Locate every global, project, nested, and override instruction candidate.
• [ ] Confirm the remote process can read each candidate.
• [ ] Check file ownership, mode, encoding, and line endings.
• [ ] Confirm DSH_HOME points to the intended runtime state directory.
• [ ] Remove or isolate stale session state for the test.
• [ ] Start a clean session after the file is present.
• [ ] Run the same marker task used locally.
• [ ] Compare the observed instruction set, not just the final code change.
• [ ] Keep a fallback directory containing the minimal repository and known-good rules.

If the remote environment cannot be restored quickly, use the fallback directory and a clean session. This is safer than continuing production work while you are unsure which project policy the Agent received.

A remote Mac is useful when you need a stable Apple Silicon workspace for repeatable development, but it does not remove the need for path, permission, and session verification. If you are evaluating a managed environment, review Mac development use cases and confirm workspace delivery before moving a team repository.

For operational handoff, write down the expected workspace path, the intended project root, the runtime home directory, the instruction candidates, and the marker used for acceptance. This turns an environment migration into a repeatable delivery test rather than an informal “the Agent seems different” report.

Final decision

Choose “rewrite the rules” only when the marker proves that the file is loaded but the Agent still misinterprets a clear instruction. Choose “fix the environment” when the marker is absent, changes only after a new session, or differs between local and remote runs. Choose “split the file” when a minimal instruction set works but the full document does not.

Do not solve a context-loading problem by endlessly increasing AGENTS.md. Large background sections, duplicated CLAUDE.md content, hidden overrides, and stale sessions can all make a longer file harder to validate.

If your current setup is a local Mac, a shared Windows or Linux host, or an improvised remote environment, the recurring weaknesses are usually the same: the launch path is not standardized, permissions drift after migration, and every developer may retain a different session state. A managed Mac environment can provide a cleaner baseline when you need temporary DeepSeek Harness capacity, reproducible workspace delivery, and a controlled remote restart path. KVMFLUX is worth considering for short-lived testing or team validation; for permanent heavy workloads, physical-device access, or a repository that must remain continuously mounted, owning a dedicated Mac may still be the better choice. Start with KVMFLUX plans only after the root path, DSH_HOME, and permission checks are part of your acceptance process.

For a broader environment review, use the KVMFLUX Mac workspace overview and carry the same marker-based test into every new machine. That turns “the Agent ignored my rules” into a traceable difference between discovery, context assembly, and session refresh.

FAQ