Project Instruction Files: Three-Tier Loading, Import Expansion, and the System Prompt's Merge Order
Make the agent know the house rules the moment it enters a repo: implement discovery and loading of user-level, project-level, and directory-level instruction files, support imports between files, define a deterministic merge order and conflict rule, and give the user one command that shows exactly how the final system prompt was assembled.
Today's Goals
- Implement discovery and loading of three tiers of instruction files, and explain each tier's scope and priority
- Implement import expansion with cycle detection and a depth cap
- Define an explainable merge order, and provide one command that shows the user where the final result came from
Yesterday solved "what to look at this once"; today solves "what it should know every time." When you finish, scroll back up and tick the three goals off.
Plain-Language Walkthrough
The team handbook: which pages to read on day one, and whose word counts
The new hire can work now and knows which file to open. But notice that every morning you repeat the same few sentences: we do not write semicolons; run tests with node --test, not npm test; run the tests before changing code to confirm they are red; use only node:assert/strict for assertions.
By the fifth repetition you realize these should not be said daily — they belong in a handbook pinned to their desk.
mca's handbook today is one system prompt hard-coded in the source. To make it "know the rules the moment it enters a repository," the handbook must live in files. And the moment it does, a question appears: who writes this handbook?
The answer is all three, and their scopes differ:
- I have preferences: answer in my language, do not restate my question. That holds in every repository.
- This repository has rules: code style, how tests run, which directories not to touch. Everyone entering it should follow them.
- This area of code has extra rules: after changing anything under
src/, immediately run the narrower test command.
Three handbooks, three scopes, widest to narrowest. So today's work has a shape: three tiers of instruction files, each discovered, merged in a deterministic order into one system prompt. The order is one sentence — more specific goes later, and on conflict the later one wins.
That rule sounds bland, and it is the source of all of today's engineering. Because "the later one wins" means the earlier one must actually disappear, not both remain for the model to choose between; it means the user needs a way to see which one won; and it means those files import one another, and imports bring cycles, depth and boundary problems.
Interview questions
For layered project instruction files, how do you decide precedence, and who wins on a conflict?分层的项目指令文件,优先级怎么定?冲突时谁赢?
Common in ChinaCommon overseasBasic#layered-config#system-prompt🔒 Unlock this chapter to see the answer keys.
If instruction files can import one another, what safety limits would you add?指令文件支持互相导入,你会加哪些安全限制?
Common in ChinaCommon overseasIntermediate#imports#safety-limits🔒 Unlock this chapter to see the answer keys.
How do you make the final system prompt explainable to the user, and why is that worth doing?怎么让最终的 system prompt 对用户可解释?为什么这件事值得做?
Common in ChinaCommon overseasDeep dive#observability#prompt-assembly🔒 Unlock this chapter to see the answer keys.
