From 8e435b748efa1a27fbc46d40e328741c6c7985ac Mon Sep 17 00:00:00 2001 From: Amburi Roy Date: Mon, 8 Sep 2025 07:37:15 +0200 Subject: [PATCH 1/3] feat: add implementation strategy for existing docs --- patterns/1-initial/ai-code-generation-context.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/patterns/1-initial/ai-code-generation-context.md b/patterns/1-initial/ai-code-generation-context.md index b742729ee..aa70e6841 100644 --- a/patterns/1-initial/ai-code-generation-context.md +++ b/patterns/1-initial/ai-code-generation-context.md @@ -105,6 +105,8 @@ Create an `innersource-ai/` folder in the repository root containing: **Naming Convention**: The suggested file and folder names follow industry common practices. However, codebase owners may choose alternative names that are more discoverable and relatable to their specific project or codebase. Any chosen naming convention should be clearly documented and communicated to contributors through proper documentation. Should files like [AGENTS.md](https://agents.md) become standard in the future, the naming conventions in this pattern might be adapted accordingly. +**Handling Existing Documentation**: If files like `ARCHITECTURE.md` already exist, the pragmatic approach is to keep them in their current location and add lightweight reference files in `ai-context` that point to them. When the architecture docs, style guides, or other materials are in Confluence or similar external systems, the `ai-context` 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 `ai-context`, but that requires more effort. The approach is flexible enough to support either approach—or even a hybrid—depending on what works best for the repository. + ### Usage Patterns #### For Contributors From 2b1f1bf77c06e7394d8b2355589e8621113cfdc3 Mon Sep 17 00:00:00 2001 From: Amburi Roy Date: Mon, 8 Sep 2025 07:40:00 +0200 Subject: [PATCH 2/3] chore: make folder name consistent --- patterns/1-initial/ai-code-generation-context.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/patterns/1-initial/ai-code-generation-context.md b/patterns/1-initial/ai-code-generation-context.md index aa70e6841..e3edb6021 100644 --- a/patterns/1-initial/ai-code-generation-context.md +++ b/patterns/1-initial/ai-code-generation-context.md @@ -105,7 +105,7 @@ Create an `innersource-ai/` folder in the repository root containing: **Naming Convention**: The suggested file and folder names follow industry common practices. However, codebase owners may choose alternative names that are more discoverable and relatable to their specific project or codebase. Any chosen naming convention should be clearly documented and communicated to contributors through proper documentation. Should files like [AGENTS.md](https://agents.md) become standard in the future, the naming conventions in this pattern might be adapted accordingly. -**Handling Existing Documentation**: If files like `ARCHITECTURE.md` already exist, the pragmatic approach is to keep them in their current location and add lightweight reference files in `ai-context` that point to them. When the architecture docs, style guides, or other materials are in Confluence or similar external systems, the `ai-context` 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 `ai-context`, but that requires more effort. The approach is flexible enough to support either approach—or even a hybrid—depending on what works best for the repository. +**Handling Existing Documentation**: 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. 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 approach is flexible enough to support either approach—or even a hybrid—depending on what works best for the repository. ### Usage Patterns From 50a586c95de8ff75e96a9e703ef6d7f0a3eec84f Mon Sep 17 00:00:00 2001 From: Amburi Roy Date: Tue, 9 Sep 2025 06:52:32 +0200 Subject: [PATCH 3/3] feat: add file name to the naming convention --- patterns/1-initial/ai-code-generation-context.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/patterns/1-initial/ai-code-generation-context.md b/patterns/1-initial/ai-code-generation-context.md index e3edb6021..7bc88a5f6 100644 --- a/patterns/1-initial/ai-code-generation-context.md +++ b/patterns/1-initial/ai-code-generation-context.md @@ -103,7 +103,7 @@ Create an `innersource-ai/` folder in the repository root containing: **Context Efficiency**: Start with core documentation files (~1000 words of context) to balance context value with AI tool costs. Expand strategically based on measured impact on review cycles and code quality. -**Naming Convention**: The suggested file and folder names follow industry common practices. However, codebase owners may choose alternative names that are more discoverable and relatable to their specific project or codebase. Any chosen naming convention should be clearly documented and communicated to contributors through proper documentation. Should files like [AGENTS.md](https://agents.md) become standard in the future, the naming conventions in this pattern might be adapted accordingly. +**Naming Convention**: The suggested file and folder names follow industry common practices. However, codebase owners may choose alternative names that are more discoverable and relatable to their specific project or codebase. Any chosen naming convention should be clearly documented and communicated to contributors through proper documentation. Should files like [AGENTS.md](https://agents.md) and `.aiignore` become standard in the future, the naming conventions in this pattern might be adapted accordingly. **Handling Existing Documentation**: 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. 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 approach is flexible enough to support either approach—or even a hybrid—depending on what works best for the repository.