Design a layered instruction architecture with repository-wide defaults, path-specific scoping, and the three-axis context model that keeps AI guidance precise and maintainable.
Transcript12 entries
Instructor:One global rule that covers the frontend, backend, and tests. Sounds clean. Until the model starts applying those test conventions to backend code or frontend code, this is Lesson 03. Instruction architecture. We will design layered instruction files, so the right rules reach the right tasks without flooding the entire context. By the end, you know how to split global, path-scoped, and task-specific rules, so the assistant behaves differently in different folders. Before the example, here is the one mental model to keep. Instructions are partitioned. They load automatically. Agents and skills are selected. Prompts are invoked on demand.
Instructor:That routing model is why the same system can behave differently in different files without repeating anything. The example we will work with is intentionally narrow. Intentionally narrow. We create one pure rules module and one matching test file. That gives the clearest view of scoped instruction layering. The change we are requesting is a very niche. It's a very specific behavioral requirement. Very difficult for AI to infer on its own. That's why we chose this scenario. And the example code has around 200 files and a lot of context to read. And we would like to see: can we deliver it with a minimal context load? Because the rules and tests should activate different instructions automatically, this should be a good way to achieve it. Before we get here in the flow chart, let's go into VS Code and understand it by ourselves.
Instructor:So we are in VS Code, and the example code is checked into GitHub. You can download and try it yourself. We just run our wrapper, which is utility.py. And it's running basically our Copilot CLI demo. It removed the source. Now it has copied the new source and is actually running the Copilot CLI command right now. So we can see here what we are anticipating. If I refresh this, we would anticipate two files with precision-engineered patterns to be validated. What is LEGAL-218? Anyone who works on any kind of financial system, they would know what this law is. It's a very niche requirement and not specifically handled by AI unless explicitly provided. When the event, false positives, and hard negatives are described, it also directs the tests clearly. We have given this constraint using this layered instruction set.
Instructor:If we carefully see this instruction set, all the instructions have some sort of a blocking which will ensure that the correct instructions are applied when the correct module has been loaded. Now here is one thing, and I would say this as more of a design tip on how to design this. The folder structure of code and the naming convention of files can actually really be helpful when designing this layered instruction system. For example, if you develop a naming convention for a file that can horizontally provide segregation, such as like something.horizontal.cli. Horizontal would be anything: tests, business, or whatever horizontal module you want to apply there. Or you provide this segregation of a business domain using a folder structure.
Instructor:By doing so, you allow the glob pattern to maintain a very clean instruction layer on top of each and every section of code. And that will allow you to create the instructions very smartly without any context bloat. Now let's go back to our example. The example is finished. Let's refresh what we did. It is here. As a result, we did exactly what we wanted with these two files, which is as expected. And if we see the demo page here, we got these files added. And notification channel disable rules: it provided the correct hard positives and negatives. It has added the LEGAL-218 restriction and the SMS requirement. That's perfect. Mandatory events have been provided correctly.
Instructor:And then the tests have been applied as we anticipated, all the hard positives and the hard negatives have been clearly defined, which is what we wanted to achieve. Now here is the reason why it achieved that: because of the layered instructions. Otherwise, for AI on its own, to achieve this is very difficult. Let's see what it did. So this was the prompt that was provided, and the CLI achieved the same objective. If we want to visualize this, there is an assessment file always generated after this code runs. And if we see this assessment file, then it has validated all the standards we have set: context utilization, validation, prompt alignment, change correctness, which validated all of them. and objective completion, all of that, plus the context trail, which will be very helpful to understand how the context led the agent in order to observe as well as discover different context. And eventually it managed to provide the right output.
Instructor:So we can see here that toward the end we managed to write, after compiling the whole context that was needed. And that's what I would call very much a context success. So let's go back to the presentation and find out, on the front, what actually happened? So first, it opened the route file while the global layer combined with backend.instructions.md. The assistant now saw the route module, the pattern, the authorization middleware, and the route expectation before it could even answer. Then it moved to rule authoring, where actually the rule layer was activated, and it figured out where the clear expectation was set for the LEGAL-218 rule, and also for the other exceptions that were mentioned in there.
Instructor:So without overriding other exception, it just managed to create a very specific patch, which we were anticipating. And this is where the critical idea of decision engineering with AI-assisted programming does exist, because without that, AI on its own finds it very hard to deliver this kind of small and very precise patch. It opened middleware, then it opened the business rules authoring, and then it switched to authorization security conventions, and then immediately applied the correct security instructions which were required. So the session, as it progressed, changed a couple of layers: first backend, then routing, and then security. In routing also, it identified the very important exceptions, especially I had left some specific exceptions to be covered with California law, and they all got handled. Now it could go further. Then it moved to the testing instructions.
Instructor:So now the persona it had obtained was the test persona, and it did all the unit testing that we anticipated, especially the false positives and negatives, which are very hard for AI to understand and implement without clear assistance from external context. And this is what actually got achieved there. The design lessons are simple. Keep the repo-wide file lean. Push the domain rules into the scoped files. Do that segregation either by using file patterns, editor-specific patterns, or folder paths. Let the file path decide what matters. In our run, the model read about 35 files, and there were more than 200 files available to read. So that's pretty much a success in that context. It made 31 to 32 tool calls in under three minutes. It created a pure rules module plus the test file.
Instructor:It corrected some of the unused imports. That decision comes from the scoped instructions, not the prompt. One quick tip to create smart instructions. You will obviously use the slash create-instruction command in VS Code Copilot Chat. Build a targeted instruction file with the front matter and the body as you wish. You can also type slash instructions, open the configuration, and edit your prompt. But here is my one piece of advice. If you use that command, the AI does generate a very effective instruction starter. I would always recommend going and manually editing the instructions as you need. Ensure there is broad applicability. Ensure there is clear discovery and ensure there is no ambiguity. There must be a graph architecture where the graph can lead you further and further down the line. to the context you would need, and eventually end with the code.
Instructor:Next lesson, in Lesson 04, we cover planning workflows, prompt files, and read-only planning agents. So this is very much where we wrap Lesson 03. Now here is my question for you: Have you ever had a single global rule file that caused more harm than help? Maybe a test rule that leaked into production code or backend conventions that then fused with the frontend. Tell me what scopes you would carve out in the comments. The best comment and question will get an exclusive live session. We have so much experience to share, especially when we work with clients. We learn a lot of new things. In those sessions, we bring everyone in to share their own experiences, their real-world experiences. So make sure you comment and bring your real-world experience. We always appreciate that.
Instructor:Now hit subscribe and turn on notifications so I can see you in Lesson 04 straight away as it gets released. I'll see you in the next session.
Learning Objectives4
- Describe the difference between repository-wide, path-specific, and agent-scoped instruction patterns
- Explain how instruction layering reduces irrelevant context and conflicting guidance
- Use applyTo scoping to encode framework- or domain-specific rules
- Apply the three-axis context model to organize customization files
Setup Instructions
Clone the repository
Clone the course repository to your local machine to follow along with the code examples.
bash
git clone https://github.com/nilayparikh/tuts-agentic-ai-examples/tree/main/ctx-sdlc/lessons/03-instruction-architecture
cd $(basename https://github.com/nilayparikh/tuts-agentic-ai-examples/tree/main/ctx-sdlc/lessons/03-instruction-architecture)Create a virtual environment
Create an isolated Python environment for the project dependencies.
bash
python -m venv .venv
source .venv/bin/activate # or .venv\Scripts\activate on WindowsInstall dependencies
Install all required packages from the requirements file.
bash
pip install -r requirements.txtnilayparikh/tuts-agentic-ai-examples/tree/main/ctx-sdlc/lessons/03-instruction-architectureGitHub
Complete source code for this lesson.
github.com/nilayparikh/tuts-agentic-ai-examples/tree/main/ctx-sdlc/lessons/03-instruction-architectureQ&A
Q & A
Q
Why is one huge instruction file a problem?
It loads irrelevant guidance for unrelated tasks, wastes context budget, and becomes difficult to maintain as frameworks and domains evolve.
Q
What does the description field really do?
It is not just documentation. It is a semantic routing hint that helps the runtime decide when a file is relevant even outside strict path matching.
Q
Where do agent-specific rules belong?
Inside the relevant .agent.md file, because those rules belong to a role on the horizontal axis rather than to a file path on the vertical axis.