Using AGENTS.md in VS Code without turning it into fluff

Introduction

If you use AI seriously in VS Code, sooner or later you run into the same problem: the model is not missing syntax, it is missing context. Not generic context either. Project context. What commands to run. What not to touch. When to ask. What counts as done. Which checks are real, and which are wishful thinking. In other words, the things a competent teammate would learn after a few days in the repository.

This is the gap AGENTS.md is meant to fill. The problem is that many examples drift in one of two bad directions:

• they become vague value statements that sound nice and help nobody
• they become giant dumping grounds for every preference the team has ever had

Neither is good. If the file is vague, the agent ignores the parts that matter. If it is bloated, both humans and models stop treating it as operational guidance.

The approach I find sensible is stricter than that: put the hard rules first, keep them compact, then put the rationale below a clear divider. Humans get a fast readable contract. The AI gets the richer explanation when it needs to reason about edge cases.

This layout is not magic, but it does solve a real problem.

What AGENTS.md is actually good for

The official idea behind AGENTS.md is straightforward: it is a predictable place for agent-facing repository instructions. VS Code supports it directly as always-on workspace guidance, which makes it useful if you want your rules to live in the repository instead of being repeated in every prompt. In practice, the strongest use cases are boring in a good way:

• exact build and test commands
• boundaries the agent must not cross silently
• escalation points for vague or risky work
• validation steps before the agent declares success
• repository-specific constraints that are not obvious from reading code

That is the key point. AGENTS.md should reduce ambiguity, not express personality.

Where AGENTS.md stops and skills start

VS Code gives you more than one customization surface, and mixing them together creates unnecessary mess.

At a high level, I think the split should be this:

• AGENTS.md for always-on project rules
• *.instructions.md for file- or task-scoped rules
• skills for reusable workflows, domain knowledge, and quality bars

That separation matters because the files solve different problems.

For example, task-specific guidance such as a debugging workflow, a release checklist, or a commit-style policy does not belong in AGENTS.md. A repository should not force every task to carry that kind of guidance. A skill is a better place for it, because it becomes available when relevant and stays out of the way when it is not.

The compact-first pattern

The most useful pattern I found during this research is simple: do not make the reader work to find the contract.

Start with the rules, and keep them terse. Then add a divider and explain the reasoning below it. That gives you two benefits at once:

1. A human can scan the top section in seconds.
2. The model can still use the lower section to resolve ambiguity more rigorously.

Here is the shape in abstract form:

## Rules

1. Ask when intent is unclear.
2. Do not invent facts.
3. Persist progress and finish meaningful work batches cleanly.

---

## Context and Rationale

Explain why those rules exist, when they matter, and what exceptions are real.

This pattern makes sense for AGENTS.md, and I think it also makes sense for skills.

There is one caveat. The lower half must add meaning. If it just repeats the same bullets in longer sentences, it becomes duplication, and duplication rots.

Why this makes sense in practice

I think this is sensible guidance, yes, but only in a disciplined form. The reason is not aesthetics, but failure handling.

When instructions are only long-form prose, people stop reading them and the important rules disappear into paragraph soup. When instructions are only terse bullets, edge cases get mishandled because the model has no rationale to lean on.

The compact-first structure is a compromise that actually respects both sides:

• humans need fast scanning
• AI systems need enough explanation to apply the rules consistently

So the recommendation is valid, but it is not universally good by default. It works when:

• the top section contains real rules, not slogans
• the lower section adds decision-making context
• both sections are maintained together

If those conditions are not met, the format degenerates into duplication.

A note on commit-message rules

This same two-layer pattern is probably a good fit for a future commit skill, but there is a distinction worth making.

Some commit conventions are broadly recognized. Conventional Commits are the clearest example: type(scope): message is a real, useful structure.

Other rules are pure team policy. For example, a hard cap of 15 words is not a standard. It can still be a good discipline rule, but it should be presented honestly as a house rule layered on top of the standard.

The same distinction applies to commit bodies. You will sometimes see teams argue that commit messages should never have a body at all. That can work, but it is still a local workflow policy, not a universal rule. That said, a team can sensibly decide to ban commit bodies if the surrounding process is strong enough, for example when:

• commits stay atomic
• tickets or ADRs hold the durable rationale
• the repository culture actually links changes back to those sources consistently

Without those conditions, banning commit bodies can just throw context away. So I would not frame never use commit bodies as general best practice, but as a workflow choice that can be valid under the right conditions.

What I would put in a starter AGENTS.md

If you are setting up AGENTS.md for a small project in VS Code, I would start with rules like these:

1. Do not optimize for pleasing the user. Optimize for correctness.
2. Surface bad assumptions and vague intent early.
3. Ask when facts or scope are unclear.
4. Present viable options when tradeoffs are real.
5. Persist progress in small resumable steps.
6. Finish meaningful work in clean, resumable batches.
7. Do not invent facts about the project.

That is enough to materially improve behavior without turning the file into a handbook.

Conclusion

The useful part of AGENTS.md is not that it lets you tell the AI what kind of person you wish it were. The useful part is that it gives the repository a place to define operational truth.

For that to work, the file has to stay sharp. Put the rules first. Put the rationale below. Keep both honest.

That same pattern appears strong enough to reuse in skills too, as long as the expanded section earns its space.

In the next part of this series, I want to look at skills more directly: what belongs there, what does not, and how far it makes sense to push workflow-specific policies such as commit rules. Stay tuned!