Context Engineering: How a Checked-in ‘Constitution’ Keeps Your AI Coding Agents on Track
Hey fellow devs!
Have you ever tried using an AI coding assistant on your project, only for it to generate code that uses outdated library versions, ignores your project’s styling rules, or breaks your architectural boundaries?
By default, AI agents write generic code. They draw from the average patterns on the public internet, not your team’s specific practices. To fix this, you don’t need to retrain a model. You need to practice Context Engineering. Let’s look at how checking in a simple “constitution” file can completely transform your team’s AI-assisted workflow.
What is Context Engineering?
Context Engineering is the practice of structuring and documenting your codebase’s rules, stack, and architecture in a way that AI agents can easily parse and respect.
Instead of writing a feature spec and hoping the AI knows how to structure the classes, you check high-level system rules directly into your repository. These files—often named agent.md, .cursorrules, or gemini.md—serve as the permanent context for any AI agent interacting with the repo.
On our latest podcast, I explained the distinction between feature-level specs and high-level rules:
Pedro: “For each of our services, we need to have a spec. It’s not a spec we call it rules—we’ve called it rules since the beginning. Today, everyone calls it a Claude or Gemini markdown file. You put it inside the repo, and what this file does is exactly state what standards this repository is following. This is something that is not feature-wise; it’s high-level project-wise context that stays with your repo and never leaves.”
The Repo Constitution: A Virtual Team Mentor
A repo constitution is a markdown file in your root directory that specifies: → Your exact technology stack (e.g. Java 21, Spring Boot 4.0, Spring Data JPA). → Architectural boundaries (e.g. “Do not call repository layers directly from the controller layer”). → Coding standards (e.g. “Always write constructor-based dependency injection”).
When you or your team members open an AI coding agent, it reads this file automatically. When developers generate code or submit pull requests, the AI reviews the code against this “constitution” and catches violations before a human reviewer has to look at it.
Yugo shared the impact this has had on his engineering team:
Yugo: “This is very powerful because you start to document the behavior and the practices that your team actually follows, and you are passing them through to the agent. Having it documented in your higher-level specifications… means that if you have a new joiner on the team, they don’t break the standards. The agent tells them: ‘Oh, you can’t do that because of this and that.’ It starts to teach the developer because there is a rule we wrote.”
This setup has had a massive impact on mentoring junior devs and interns:
Yugo: “I’ve seen my interns start getting productive much earlier now, and the pull requests they are sending are much more mature. The mature output is because the AI agents are helping them write code that fits the repo standards.”
Documentation is No Longer Dead
In traditional software development, documentation was often seen as a chore. Developers rarely read it, and it quickly went out of date.
But in the AI era, documentation is active code context. Your AI agents read it on every prompt. If you write clean, structured documentation about your database design, API design, and system boundaries, your AI will generate significantly better code.
If you want to write better code with AI, stop focusing purely on coding and start writing your repo constitution.
Does your repository have a .cursorrules or agent.md file? What is the most important rule you would include in it? Let me know in the comments below!
Watch the full video here to see our discussion.
Happy coding!
Cheers,
Pedro Cavalero
