Compact Project Semantics for a Coding Agent: 4 Files Instead of Confluence

⚡ The gist in 5 seconds - The author suggests doing without heavyweight documentation and building a compact context layer for a coding agent — just four short files. - The approach is available as a repository with a ready-made mini-example simulating a weekly quota module. - Limitation: the method is designed for small projects; for dozens of teams or long-lived context, the author recommends looking at OpenViking. ### 🔍 What was found In an article by dgerasina dated September 25 on Habr, SDD practice is described at a reduced scale. The point is to give the agent intent, not just code. In the test example, the agent found a method, added a counter, and wrote a test, but failed to account for the fact that the limit is counted per user and that a rejected attempt does not consume the quota. This happened because the model received the code but not the domain semantics. The minimal set of files looks like this: - agent-context/index.md — navigation: where to go with a task of a given type; - domain.md — terms and invariants (e.g., "a week starts on Monday at 00:00 UTC"); - contracts.md — public contracts visible to external calling code; - features/*.md — boundaries and definition of done for a specific feature. The author offers a filter: if a statement can be reconstructed from the source code without loss, don't copy it into agent-context — a path in index.md is enough. But invariants like "a rejection does not consume the quota" cannot be reliably extracted from code; they must be written down by someone who knows the domain. A short route is proposed for the agent: first read index.md, then for a task about limits — domain.md, contracts.md, and features/weekly-limit.md, after which open the referenced sources and tests. Definition-of-done criteria should be matched against tests, and the public contract must not be changed without updating contracts.md. ### 💡 Why it matters The practical benefit is that the approach gives the agent exactly the semantics that models lack: the "why," "what must not be broken," and the differences between similar terms. This reduces the risk of regressions — instead of a confident but incorrect change, the agent first checks against the invariants. Moreover, the set of files is minimal, and the PR rules are simple: public API changed — update contracts.md; a new invariant appeared — update domain.md and the test. Automate only the obvious, such as comparing generated OpenAPI against the committed schema. ### 🧩 Context The author emphasizes that they are not proposing to copy the entire Spec Kit workflow — only to make intent accessible to the agent and tie it to tests. For a small project, these files are enough, and they do not replace architectural review. When the context lives longer than one feature, memory across sessions and many sources appear, the author recommends OpenViking — a context base for agents with a virtual file system. But installing it for a pet project with two tests is "like calling in a crane to move a stool." Until that point, you can do without RAG and autonomous orchestrators.

🔗 Read on habr.com