Coding Guidelines for Your AI Agents

As software developers, we invest significant time and effort learning various technologies, understanding design patterns, avoiding anti-patterns, and striving to write clean, maintainable code. Over the years, this knowledge becomes second nature, guiding our decisions as we design systems, write features, and review code.

But the landscape is evolving fast.

We’re now entering a new era of software development, where AI agents are becoming our pair programmers, code reviewers, and even architects. These AI tools are powerful, but they’re only as good as the instructions we provide. If we want these agents to generate code that’s idiomatic, secure, maintainable, and aligned with our standards, we should communicate our intent very clearly to the agents to avoid any assumptions.

Why guidelines matter more than ever

Nowadays, asking an AI agent to “create a Spring Boot REST API” will give you a working result, but it may:

• Miss pagination for list APIs.
• Use field injection instead of constructor injection.
• Skip error handling or logging.
• Not adhere to your project’s package structure or naming conventions.

This is where technology-specific coding guidelines come into play. They provide:

• A clear standard for how code should be written in a given language or framework.
• A reference point for developers to onboard quickly and write consistent code.
• A contract to share with AI agents when prompting them to generate code.

Our goal: a living catalog of AI-friendly coding guidelines

We’re working on building a catalog of guidelines – a developer-centric and AI-ready resource that outlines best practices for commonly used technologies like Java, Spring Boot, Spring Data, Spring Security, Docker, Testcontainers, and more.

The guidelines will include:

• Preferred coding styles and conventions
• Dos and Don’ts (best practices vs. anti-patterns)
• Common “gotchas” to avoid
• Real-world code examples with explanations

How this helps developers and AI agents alike

For developers, this catalog becomes a trusted reference – something they can consult before implementing a feature, doing a code review, or mentoring a teammate.

For AI agents, it becomes recommended guidelines – a set of standards you can paste into a prompt and instruct agents to follow when generating code.

Example use case

You could start a prompt with:

Generate a Spring Boot REST controller following these guidelines:

• Use constructor-based dependency injection
• Return ResponseEntity with proper status codes
• Validate input using @Valid and return meaningful error responses
• Avoid using Optional in request bodies

And the result? The generated code is more aligned with your expectations, saving time on refactoring and reviews.

How to use guidelines with Junie

Junie is an autonomous AI coding agent from JetBrains. You can specify your coding style, best practices, and general preferences by specifying your desired guidelines in the .junie/guidelines.md file so that Junie will follow them while generating code.

Check out the junie-guidelines repository, which has a catalog of guidelines for various technologies. 

You can add all the guidelines for various technologies that you are using into the .junie/guidelines.md file and delegate tasks to Junie. Junie will take these guidelines into consideration while generating the code so that you don’t have to add these guidelines in each prompt. 

How to use Junie guidelines in existing (legacy) projects?

For greenfield projects, you can use the guidelines from the catalog and start building your application. But what about existing applications that already follow certain conventions and patterns?

You can ask Junie to create a guidelines.md file that includes the coding conventions being followed in the current codebase so far.

Once the guidelines.md file is generated, you can tweak it to add more guidelines or update the existing ones as needed.

Summary

This living catalog of AI-friendly coding guidelines is more than just documentation. It’s a community-driven playbook designed to keep our codebases consistent, reliable, and future-ready. By pooling our collective expertise in areas like Java, Spring Boot, Docker, and Testcontainers, we’ve created a single source of truth that benefits both human developers and AI-powered tools. Whether you’re implementing a tricky feature, conducting a code review, or fine-tuning your AI prompts, these guidelines will save you time and prevent common pitfalls.

NOTE: Some guidelines are opinionated, and your views and those of the author may differ on certain points. Feel free to modify the guidelines to suit your needs and team preferences.

We plan to publish the first batch of guidelines soon and open it for community contributions. If you care about code quality in the age of AI, this is your chance to help define what good AI-generated code looks like.

We are working on creating guidelines for various programming languages including Java, Kotlin, Python, Go, JavaScript/TypeScript, etc.

We invite you to visit the junie-guidelines repository on GitHub, explore the existing sections, and, most importantly, contribute your own guidelines.

Have a favorite pattern, a memorable gotcha, or an example that perfectly illustrates a best practice? Submit a pull request! Your contributions will not only strengthen the catalog but also help shape the future of AI-assisted development. Let’s build this resource together and set a new standard for coding excellence.