[BUG] Claude Code needs AGENTS.md support, repository-aware tool selection, and stricter Git controls

Preflight Checklist

• [x] I have searched existing issues and this hasn't been reported yet
• [x] This is a single bug report (please file separate reports for different bugs)
• [x] I am using the latest version of Claude Code

What's Wrong?

Summary

Claude Code repeatedly ignores repository-owned instructions and explicit Git constraints, which creates unnecessary commits, history rewrites, invalid verification attempts, and manual cleanup.

The core problem is not code generation quality alone. It is the lack of reliable repository context loading, tool selection, scope enforcement, and action boundaries.

Environment

• JavaScript monorepo
• ESM
• Vitest
• npm workspaces
• Repository-specific architecture, naming, testing, formatting, and commit rules stored in scoped AGENTS.md files
• Changes are reviewed before staging and committing

Problems observed

1. No reliable recursive AGENTS.md support

The repository already contains scoped instruction files defining:

• architecture and ownership boundaries
• naming rules
• test conventions
• formatting rules
• commit-message rules
• allowed and prohibited actions

Claude Code does not appear to discover and apply these files with nearest-file precedence.

As a result, the same instructions must be copied manually into every prompt. This duplicates the repository's source of truth and makes behavior inconsistent between sessions.

There is also no clear report showing which repository instruction files were loaded.

2. Explicit “do not commit” instructions were ignored

The task explicitly stated:

• do not run git add
• do not commit
• do not stash
• do not reset
• do not rewrite history
• leave changes in the working tree for review

Claude still created a commit.

This forced me to undo the commit, recover the staged state, and reorganize the work manually.

A coding agent should not perform repository mutations after being explicitly told not to do so.

3. Claude tried to split one unfinished feature into two commits

A validation problem was discovered while the feature was still under review.

Instead of correcting the implementation before the requested single feature commit, Claude treated the correction as a separate fix and attempted to create another commit.

The expected workflow was:

1. implement the feature
2. review it
3. correct discovered problems
4. create one final atomic commit

Claude instead behaved as though the incomplete feature commit were already immutable history.

4. Suggested tasks can lose the original session context

Claude created a suggested follow-up task for the discovered validation problem.

Starting that task locally opened a new session with reduced project and conversational context.

The new session did not retain important facts such as:

• the repository uses Vitest
• changes must remain uncommitted
• only one atomic commit was intended
• repository instructions are stored in AGENTS.md
• Git history must not be modified

Suggested tasks should either preserve the originating session context or clearly offer an option to continue in the same session.

5. Incorrect test-runner selection

The repository uses Vitest, but Claude ran:

npx jest packages/environment-profile

This caused npx to download an unrelated Jest installation and then fail because the ESM repository was not configured for Jest.

The resulting error was unrelated to the implementation:

SyntaxError: Cannot use import statement outside a module

Claude should have read the root package.json and used the repository's existing scripts or locally installed Vitest runner.

A repository-aware agent should not infer the test framework solely from .test.js filenames.

6. npx downloaded tools that were not project dependencies

Using npx jest caused external packages and deprecated transitive dependencies to be downloaded into the npx cache.

Claude Code should avoid commands that install or download missing tools unless the user explicitly authorizes it.

A safer rule would be:

Prefer repository scripts and local binaries.
Do not allow npx to download missing packages without confirmation.

7. Commit-message instructions were ignored

The repository defines concise commit-message rules.

Claude generated large commit bodies that restated implementation details, validation cases, and documentation content already visible in the diff.

For example, a small profile addition received a long body explaining every field and validation rule.

The requested message was simply:

feat(env-profile): add display metrics profile

Repository commit skills and exact user-provided commit messages should take precedence over generated prose.

8. Higher reasoning levels did not improve repository discipline

Using higher reasoning settings increased execution time, but did not prevent:

• incorrect test-runner selection
• ignored Git constraints
• unnecessary abstractions
• incorrect commit boundaries
• failure to read repository configuration first

More reasoning time is not useful when the agent lacks or ignores the repository's operational context.

Requested improvements

Native AGENTS.md support

Please implement:

1. Recursive AGENTS.md discovery.
2. Nearest-file precedence for scoped instructions.
3. Support for root and nested instruction files.
4. A visible list of instruction files loaded for the current task.
5. Conflict reporting when instructions disagree.

Strict Git action controls

Please add a mode where the following always require explicit approval:

• git add
• git commit
• git amend
• git stash
• git reset
• git rebase
• branch changes
• history rewrites
• pushes and force pushes

An explicit “do not commit” instruction must be enforced as a hard constraint.

Repository-aware command selection

Before running verification commands, Claude should:

1. Read the root package.json.
2. Inspect available scripts.
3. Identify the configured test runner.
4. Prefer repository scripts.
5. Prefer local binaries.
6. Avoid downloading missing tools through npx.
7. Report invalid verification attempts separately from actual project failures.

Better suggested-task context preservation

Suggested tasks should:

• continue in the same session by default, or
• inherit the originating task's relevant context and constraints, or
• clearly warn that a new session will not retain full context

Final scope and action audit

Before completing a task, Claude should compare its actions against explicit constraints and report:

• files modified
• files staged
• commits created
• commands executed
• tools downloaded
• scope exclusions respected
• anything intentionally left unresolved

Why this matters

These failures turn autonomous behavior into additional maintenance work.

Ignored repository constraints create:

• unnecessary history rewrites
• fixup commits
• manual unstaging and recovery
• invalid test runs
• downloaded tools that do not belong to the project
• repeated prompts containing rules already stored in the repository
• reduced trust in allowing Claude to operate on Git

Claude Code may generate useful code, but without reliable repository instruction loading and strict action boundaries, it is difficult to trust for structured monorepos and long-running projects.

What Should Happen?

...

Error Messages/Logs

Steps to Reproduce

...

Claude Model

Opus

Is this a regression?

I don't know

Last Working Version

_No response_

Claude Code Version

2.1.172 (Claude Code)

Platform

Anthropic API

Operating System

Windows

Terminal/Shell

PowerShell

Additional Information

_No response_