Enhancing AI Coding Agents with Project-Specific Information

Are you using AI coding agents but finding they sometimes struggle with your project’s specific conventions or best practices?

Of course, you could wait for the next, more powerful LLM, the next smarter agent, or even attempt to load the entire codebase into every request. However, there’s a much simpler and highly effective solution that we explore in this article and the demo video below. Instead of relying on the AI to find everything out by itself, we introduce a lightweight yet impactful approach: the “project-info” file.

This file acts like a focused readme, crafted specifically for AI agents. It provides essential project knowledge in a concise format, helping the agent quickly align with your project’s conventions, best practices, and structure without unnecessary trial and error.

The video below demonstrates the concept and shows you how to create and use a project-info file within the AI-powered Theia IDE. In the remainder of the article, we expand on the same concept with additional context and explanation. Feel free to either watch the video to see it in action, read the article for a more detailed walkthrough, or explore both for a complete understanding.

The Challenge of Existing Codebases for AI Agents

AI coding agents, such as Theia Coder, are powerful, but when faced with an existing codebase, they often have to guess or explore to understand project conventions.

In the example in the video above, Theia Coder (using Claude 3.7) was asked to create tests for a service. While the generated test code itself looks good, the agent made two key mistakes based on the project’s conventions:

• It used the wrong file pattern (test.ts instead of the project’s convention spec.ts).
• It placed the test file in a generic test directory instead of following the convention to place test files in the same directory as the class under test.

This is just a simple example. Once you start using AI coding tools on a daily basis, you will likely observe similar issues where the AI fails to follow your project’s conventions consistently. Another frequent challenge is that AI agents might repeatedly misinterpret specific parts of your project or fail to understand architectural elements that don’t strictly follow common standards. These small quirks can accumulate, leading to inefficiencies and significant frustration over time.

The Problem with Relying Solely on AI Exploration

Of course, you could prompt the agent to explore more thoroughly or hope for smarter models in the future. In fact, when executing the example query used in the video (generate the tests), in over 75% of the cases, Theia Coder was able to find an existing test case and correctly follow the conventions. However, relying on the agent to discover project-specific knowledge on its own has several significant drawbacks:

• Lower reliability: For conventions, we ideally want close to 100% consistency — the agent should reliably follow the expected standards without fail.
• Loss of efficiency: Since AI agents are stateless across sessions, they must rediscover conventions each time, consuming more tokens, increasing response times, and diverting focus from the actual coding task.
• Risk of learning from poor examples: Without controlled guidance, the agent might reference outdated or non-compliant parts of the codebase. In almost all real-world projects, there are legacy or outlier files that shouldn’t serve as patterns. In the test generation example, Theia Coder could easily pick up a poorly structured test case and propagate suboptimal practices into new code.

A Simple, Real-World Inspired Solution

In practice, when facing challenges with AI agents adapting to a project, there is a strong temptation to reach for complex solutions like Retrieval-Augmented Generation (RAG), fine-tuning models, or designing intricate prompting strategies. While these approaches are powerful, they often add significant complexity and maintenance overhead.

However, if we think about a real-world analogy: When a new coworker joins a project without any prior knowledge or memory, we don’t ask them to explore the entire codebase, use an elaborate knowledge base, or force them to write hundreds of test cases to learn the project’s conventions. Instead, we simply hand them an example or share a few clear guidelines: “Here’s a good test case — follow this,” or “Here are the conventions we follow.”

This is exactly the spirit behind introducing a simple, project-specific project-info file. Rather than relying on the AI agent to deduce everything itself, we explicitly provide key examples and rules in a straightforward document. This lightweight approach ensures that AI agents can immediately align with the project’s standards — without complex infrastructure or heavyweight solutions.

Introducing Project Info: A “Readme for AI Agents”

To allow the project-info to be project specific, we place it into a workspace directory, e.g. under “.prompts” and maintain it as part of the regular code base. To integrate it into any agent, we use a Theia AI feature called “prompt fragment” – essentially a piece of text – to your project that is automatically included in the system prompt of the AI agents when you open the project in Theia.

This prompt fragment acts like a “readme for AI agents,” providing explicit information about the project that agents typically struggle to infer on their own.

Augmenting the Project Info File

To address the test-writing issues described above, in the demo video, we augment the project-info file with a short new section specifically for writing tests, including:

• Instructions to refer to two specific example files for consistency and best practices, one for the backend and one for the frontend, representing best practices in the Theia project.
• An explicit instruction stating that tests should be located in the same directory as the components under test.

The Improved Outcome

As shown in the video, running the exact same query (@Coder create tests for…) after adding this project info yielded significantly better results. The agent quickly retrieved the provided test file references. Crucially, it immediately followed the defined best practices, using the correct file pattern and placing the test in the right directory. The process was also “much faster” because the information was explicitly provided.

Best Practices for Creating and Maintaining a Project Info File

To get the most out of the project-info file while keeping it lightweight and effective, it’s important to approach its creation and evolution with a few key principles in mind:

1. Start Bottom-Up: Focus on Pain Points

Rather than attempting to document your entire project up front, begin by observing where AI coding agents you use struggle most. Typical issues include naming conventions, folder structures, test placement, or non-standard architecture patterns. Use these observations to incrementally build up your project-info file with only the most relevant clarifications.

This bottom-up strategy ensures the file remains focused and avoids overwhelming the agent with redundant or unnecessary data — especially given that modern agents can already infer many common patterns themselves.

2. Stay Concise and Context-Aware

Conciseness is key. The goal of the project-info file is not to replicate the entire documentation or codebase, but to fill in the gaps that the AI might miss. Overloading the file with generic or overly detailed information can dilute its impact. Remember that AI agents already come with extensive training and often understand well-known technologies or frameworks, especially in open source projects or projects with a very common architecture. For such projects, minimal guidance might be sufficient.

In contrast, for closed source or proprietary projects with custom setups, more explicit directions may be needed — but still, keep it targeted and precise.

3. Use References Instead of Full Descriptions

Where possible, link to examples rather than embedding full instructions. For instance, instead of explaining how to write a unit test in detail, simply reference one or two well-structured test files in your repository. LLMs tend to respond well to examples and are capable of extracting patterns from them as needed.

This approach also has the benefit of keeping your project-info lean and easy to update — and it gives the AI agent the flexibility to explore the reference when it needs more context. Also, we all know: good code is the best documentation, so avoid documenting something for the AI that it can learn from good examples in your code base directly. Just ensure your development environment supports resolving such references effectively (like Theia Coder does).

4. Make It Part of Your Workflow

Treat the project-info file as a living document that evolves with your codebase. When new patterns or conventions emerge, or when you observe repeated mistakes from AI agents, update the file accordingly. Placing it in a designated directory like .prompts and version-controlling it alongside your source code ensures it stays relevant and accessible.

5. Review and Curate Regularly

Avoid letting the file become bloated or outdated. Set periodic reminders to review its content and remove obsolete sections. Focus on what continues to be helpful, and be deliberate in what you add.

Conclusion

By using the project info feature to provide explicit guidance and examples, you can significantly improve the reliability, precision, and efficiency of AI coding agents working on your specific codebase. It allows you to enforce project conventions and best practices directly, making the AI agent a more effective and compliant member of your development workflow.

For more details on setting up the project info file in the AI-powered Theia IDE, refer to the video linked above.

Using the project info feature to provide explicit guidance and examples can dramatically enhance the reliability, precision, and efficiency of AI coding agents working on your specific codebase. Rather than expecting these tools to “just work” out of the box, it’s important to recognize that successful AI coding is not about simply buying a subscription to the latest tool — it’s about learning how to use these tools effectively, refining your development workflow, and adapting your environment and processes to suit your specific project and domain needs.

At EclipseSource, we specialize in helping teams make AI coding truly work. Our experienced consultants can dive deep into your project’s structure, your domain-specific requirements, and the tools you’ve adopted. We help you optimize and augment both the tools and your processes, ensuring that AI becomes a productive and aligned part of your development workflow.

👉 Learn how to empower your teams with AI-enhanced coding and AI-native software engineering

For more advanced scenarios — such as domain-specific environments, complex toolchains, or highly customized development workflows — we also offer expertise in building AI-native tools from the ground up. Whether you’re developing tailored extensions for Eclipse Theia or VS Code, or crafting entirely new cloud-based or web-based solutions, we support you with consulting and implementation services that bring AI to the core of your tools and platforms.

👉 Contact us to find the perfect AI-driven solution for your projects!

🧪 Try it now: Get the AI-powered Theia IDE

📖 Read more: Introducing the AI-powered Theia IDE

💼 Follow us: EclipseSource on LinkedIn

👉 Services for AI-enhanced coding and AI-native software engineering

👉 Services for building AI-powered tools and IDEs