[Pattern Draft] AI Code Generation Context

[amburi]

AI Code Generation Context - AI tools generate code that diverges from project standards and architectural patterns. Provide an AI Code Generation Context Package within repositories to guide AI tools in producing contributions that align with existing project conventions, reducing review friction and maintaining code consistency.

[welcome]

💖 Thanks for opening this pull request! 💖 The InnerSource Commons community really appreciates your time and effort to contribute to the project. Please make sure you have read our Contributing Guidelines.

If you are submitting a new pattern, the following things will help get your pull request across the finish line! 🏁

• Confirm that you have used our pattern template. Please remove any placeholder text and sections that your pattern did not need.
• We run a number of automated checks on your PR. Please review the output of those checks on the PR itself, and see if any issues got flagged that you can fix yourself.
• Make sure you have added your new pattern to the list of patterns in the main README.md. If you are unsure where to add your pattern, just let us know by commenting on your PR and we will help you.

This project has a small number of maintainers, volunteering their time to this project. So please be patient and we will get back to you as soon as we can. If we don't acknowledge this pull request after 7 days, feel free to chat to us about it in our Slack workspace.

[spier]

Hi @amburi

Great to see your contribution here!!! 🫶

Just out of curiosity: how did you find us?

I will take a closer look at your contribution later today and leave feedback on this PR.

[amburi]

Hi @spier

I have been following InnerSource for some time, and while working with it I came across the context engineering scope in the pattern. That inspired me to contribute this idea to the community.

Look forward to your feedback. Thanks! Have a great one! 😄

[spier]

@amburi could you please check if you have set permission for maintainers of the upstream repo (this repo here) to commit changes to your branch? See details of how to do this here.

I would like to push some trivial fixes back your branch/fork.

[spier]

@amburi are your using this pattern in your organization already, and would you like to mention your org as a known instance here?

If not, no problem either. However in that case I would recommend to move this pattern to the folder 1-initial instead, to indicate that this pattern has not been proven in practice yet.

[amburi]

@spier Thanks for your feedback.

Our organisation has adopted this pattern, but it is still in its early stages. To provide more details, I need the organisation's approval, which may take some time. So, I accept your suggestion and have moved the pattern to the 1-initial folder. Once approved, I will update the data accordingly and move it back to the 2-structured folder.

Also, I have enabled maintainer edits, so you can now make minor changes in this PR.

[yuhattor]

Considering that files like AGENTS.md may become standard in the future, writing specific filenames as "best practices" within patterns might not be very appropriate in this fast-moving AI world.
We need to abstract this a bit more, while at the same time, I think we should explore the possibility of adding such files as instances.

The way of thinking about passing correct information to AI is something that should be explored more in the world of InnerSource going forward. Thanks for kicking off this discussion:)

[amburi]

@yuhattor Thanks for your comment 🙂 You raise a good point about not locking into specific filenames too early, since conventions in this space are evolving quickly. At the same time, naming conventions often bring clarity and discoverability—similar to how index.html became a common default even though other names could have worked.

That’s why I suggested AGENTS.md: it could become a familiar convention, but it’s by no means the only option. To reflect both sides, I’d keep the example filename but explicitly mention that it’s flexible and can be adapted by the code owner.

Would that feel like the right balance to you?

[spier]

@yuhattor Thanks for your comment 🙂 You raise a good point about not locking into specific filenames too early, since conventions in this space are evolving quickly. At the same time, naming conventions often bring clarity and discoverability—similar to how index.html became a common default even though other names could have worked.

That’s why I suggested AGENTS.md: it could become a familiar convention, but it’s by no means the only option. To reflect both sides, I’d keep the example filename but explicitly mention that it’s flexible and can be adapted by the code owner.

Would that feel like the right balance to you?

The specific filenames and folder names have helped me to understand what they are meant to be used for. So the name itself is part of the documentation, if you will :)

I like the approach that you are suggesting though!

Maybe one could mention early on in the Solution section that neither of the file names or folder names are an industry standard of any sort, and that these names are rather used to illustrate what they are meant to be used for.

This really applies all the way up to the innersource-ai/, which is also just a name that you chose yourself, right?

[spier]

@amburi great work on this PR!!!

I left some inline comments for you to review.

In general I think we can merge this PR fairly quickly, as we then have a great starting point that we can reference and share with the broader InnerSource community to collect more experiences related to this topic.

Two overarching comments:

1. The project may already contain some of the files, which are now meant to be placed under the innersource-ai folder. e.g. ARCHITECTURE.md. How to deal with that?
2. I have a hunch that the innersource-ai folder could quickly become so comprehensive (i.e. so much to read) that no human contributor would ever read this ahead of making a contribution. So in that sense a contribution that follows all these rules would no longer be possible without the use of AI at all. Is this unfounded speculation on my part?

Aside: Once we merged this PR, please share how you crafted the AI prompt to create this pattern, so that we can use this AI Code Generation Context pattern for our patterns repo as well ;)

[spier]

@amburi thank you for your continuous work on this!

I just integrated some local improvements that I had made, merged them with your changes, and pushed everything back to your branch.

I left one more inline question related to the use of the term "package".

Also I would love to hear your thoughts on the questions in my last comment.

After that I think we can get this merged 🥳

[amburi]

@spier Thank you!

I’ve removed the term “package”.

I have a hunch that the innersource-ai folder could quickly become so comprehensive (i.e. so much to read) that no human contributor would ever read this ahead of making a contribution. So in that sense a contribution that follows all these rules would no longer be possible without the use of AI at all. Is this unfounded speculation on my part?

That’s not unfounded—it’s definitely a risk if the innersource-ai folder grows without structure. But the intention is not that contributors read everything before making a change. Instead, both humans and AI should be able to selectively draw on the parts that matter. For example, in a multi-module service, the folder might contain separate context files for each module, so a contributor only needs to review the files relevant to their work and provide those as context when generating code with AI.

The project may already contain some of the files, which are now meant to be placed under the innersource-ai folder. e.g. ARCHITECTURE.md. How to deal with that?

That’s a great point. If files like ARCHITECTURE.md already exist, the pragmatic approach is to keep them in their current location and add lightweight reference files in innersource-ai that point to them. For example — When the architecture docs, style guides, or other materials are in Confluence or similar external systems, the innersource-ai folder becomes a crucial bridge between the codebase and external knowledge. This avoids duplication and keeps the folder consistent. For projects that want tighter integration, code owners could choose to reorganize and consolidate content under innersource-ai, but that requires more effort. The pattern is flexible enough to support either approach—or even a hybrid—depending on what works best for the repository.

I look forward to your approval so we can merge this pattern soon.

[spier]

Thank you again for taking the time to work in the review feedback provided on this PR, and also for providing further explanations about your rationale for this pattern.

I was not aware of existing efforts such as AGENTS.md before. For future improvements to this pattern, we might explore the similarities and differences of AGENTS.md to this pattern, and to explicitly explain and document those.

However that can be left as future work. For the time being lets already merge this pattern, to allow us to collect further feedback from the greater InnerSource community.

[welcome]

Congrats on merging your first pull request! 🎉 We here at The InnerSource Commons are proud of you! 💖 Thank you so much for your contribution 🎁