From 2eb29ead37582ba236850208b66c279aa652f69e Mon Sep 17 00:00:00 2001 From: Martin Nygren Date: Fri, 5 Jun 2026 15:11:21 +0100 Subject: [PATCH 1/5] work in progress on advice. --- .github/instructions/git.instructions.md | 2 +- .github/instructions/github.instructions.md | 14 +------- docs/coding_standards_and_ai_advice.md | 36 +++++++++++++++++++++ 3 files changed, 38 insertions(+), 14 deletions(-) create mode 100644 docs/coding_standards_and_ai_advice.md diff --git a/.github/instructions/git.instructions.md b/.github/instructions/git.instructions.md index e12da055..264fdc00 100644 --- a/.github/instructions/git.instructions.md +++ b/.github/instructions/git.instructions.md @@ -21,6 +21,6 @@ alwaysApply: false 2. **Make changes** locally. 3. **Commit** with a clear message. 4. **Push** the branch. -5. **Open a PR** via the `github` MCP server (see `github.instructions.md`). +5. **Open a PR** via the `github` command line interface. --- \ No newline at end of file diff --git a/.github/instructions/github.instructions.md b/.github/instructions/github.instructions.md index 5bbff444..d372d0ea 100644 --- a/.github/instructions/github.instructions.md +++ b/.github/instructions/github.instructions.md @@ -7,7 +7,6 @@ alwaysApply: false ## Overview This project uses GitHub as its primary version control and collaboration platform. All code contributions, fixes, and features must go through a pull request (PR) workflow. -You have access to an MCP server named **`github`** (running `mcp-github`) which can create branches, push commits, and open PRs directly from the Continue.dev environment. See `.vscode/mcp.json` for configuration. ## Branching Strategy - **Default branch:** `main` @@ -32,25 +31,14 @@ You have access to an MCP server named **`github`** (running `mcp-github`) which 5. Small PRs are preferred — keep them focused on one logical change. ## Tooling -Use the **`github`** MCP server (configured in `.vscode/mcp.json`) to: +Use the github command line interface to: - Create branches - Commit and push changes - Open pull requests - Check PR status -## Example MCP Server Commands -You can instruct Continue.dev to: -- `Use the github MCP server to create a new branch called fix/memory-leak` -- `Push the current branch and open a pull request titled "Fix memory leak in cache manager"` -- `List open pull requests for this repo` -- `Merge PR #45 after approval` ## Automation - CI/CD runs automatically for all PRs. - Approved PRs can be merged by maintainers. -- Use **squash merging** to keep history clean. -## Notes for Continue.dev -- You are allowed to automate branch creation and PR submission using the `github` MCP server. -- If multiple PRs are required, ensure each is isolated to its own branch. -- You may request human review before merging. ``` diff --git a/docs/coding_standards_and_ai_advice.md b/docs/coding_standards_and_ai_advice.md new file mode 100644 index 00000000..cc20471a --- /dev/null +++ b/docs/coding_standards_and_ai_advice.md @@ -0,0 +1,36 @@ +# Coding agents and coding standards + +Coding agents are becoming increasingly powerful and which tool and model that scores best in test changes if not by the week at least on a monthly basis. These recommendations and instructions for coding were collected in the first quarter of 2026 when the bulk of the work to modernise the codebase for release 3.0.0 was carried out. + +Configurations for MCP servers are not included. MCP servers add a lot of power, but can also expose severe vulnerabilities. How they should be deployed is definitely not one size fits all. + +## Recommended tools for coding agents + +### clangd +https://clangd.llvm.org + +Language servers are well known by most integrated development environments but coding agents are typically not able to interact with them directly. There are several MCP wrappers that can surface a language server to a coding agent. This is, however, surfacing raw JSON responses that the coding agent has to interpret and reason around. If - as is highly recommended - you run serena then prefer to let serena handle the integration with language servers. + +### Serena +https://github.com/oraios/serena + +Probably the most important tool at the time of writing. + +### Code Context Engine + +## Coding Standards + +Keeping a consistent coding style is more important than ever as it helps both humans and coding agents. Preferred styles are document in the `.github/instructions directory` + +1. [C++](../.github/instructions/cpp.instructions.md) +2. [Bazel](../.github/instructions/bazel.instructions.md) +3. [Git](../.github/instructions/git.instructions.md) +4. [GitHub](../.github/instructions/github.instructions.md) + +## Documentation and code completion + +### Extracting compile_commands.json + +https://github.com/kiron1/bazel-compile-commands + +https://github.com/hedronvision/bazel-compile-commands-extractor \ No newline at end of file From 2b37f6d4dd869e702a57a88a22ddf497568e3ef6 Mon Sep 17 00:00:00 2001 From: Martin Nygren Date: Wed, 10 Jun 2026 11:25:10 +0100 Subject: [PATCH 2/5] work in progress on documents --- docs/coding_standards_and_ai_advice.md | 12 ++++++++++-- 1 file changed, 10 insertions(+), 2 deletions(-) diff --git a/docs/coding_standards_and_ai_advice.md b/docs/coding_standards_and_ai_advice.md index cc20471a..8010f7f8 100644 --- a/docs/coding_standards_and_ai_advice.md +++ b/docs/coding_standards_and_ai_advice.md @@ -14,13 +14,19 @@ Language servers are well known by most integrated development environments but ### Serena https://github.com/oraios/serena -Probably the most important tool at the time of writing. +Probably the most important tool at the time of writing. Serena provides semantic analysis and instructions to help coding agents stay on target. ### Code Context Engine +https://github.com/elara-labs/code-context-engine + +Creates and maintains an index of the codebase. This means that a coding agent often can read only the relevant part of a file instead of searching all the content of several files. + +As a side note, I find it interesting that vector embeddings were removed from Claude Code. My amatuer understanding is that Serena tells the agent what the code is doing and code context enginer where the interesting code. This differs from vector embeddnings which tells the coding agent which parts of the codebase looks similar. Knowing that calls to write to the database looks similar is not useful, but the information where they are and what they write is. + ## Coding Standards -Keeping a consistent coding style is more important than ever as it helps both humans and coding agents. Preferred styles are document in the `.github/instructions directory` +Keeping a consistent coding style is more important than ever as it helps both humans and coding agents. Preferred styles are document in the `.github/instructions directory`, which is where Github Copilot looks for its permanent instructions. 1. [C++](../.github/instructions/cpp.instructions.md) 2. [Bazel](../.github/instructions/bazel.instructions.md) @@ -29,6 +35,8 @@ Keeping a consistent coding style is more important than ever as it helps both h ## Documentation and code completion +DDS3 + ### Extracting compile_commands.json https://github.com/kiron1/bazel-compile-commands From 8fee3a45bb99f5a51364ddeb7ee131b765b3647e Mon Sep 17 00:00:00 2001 From: Martin Nygren Date: Fri, 12 Jun 2026 15:05:08 +0100 Subject: [PATCH 3/5] Fix doxygen_docs genrule PATH to include platform-specific tool directories Bazel constructs a minimal PATH that excludes Homebrew on macOS, causing the doxygen availability check to fail even when doxygen is installed. Co-Authored-By: Claude Sonnet 4.6 --- BUILD.bazel | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/BUILD.bazel b/BUILD.bazel index 50327287..d3263ea2 100644 --- a/BUILD.bazel +++ b/BUILD.bazel @@ -93,6 +93,11 @@ genrule( outs = ["doxygen_docs.zip"], cmd = """ set -e + case "$$(uname -s)" in + Darwin) PATH="/opt/homebrew/bin:/usr/local/bin:$$PATH" ;; + Linux) PATH="/usr/local/bin:$$PATH" ;; + MINGW*|MSYS*|CYGWIN*) PATH="/usr/bin:/usr/local/bin:$$PATH" ;; + esac DOXYFILE_GEN="$(@D)/Doxyfile.generated" OUT_DIR="$(@D)/doxygen_output" OUT_ZIP="$$(pwd)/$@" From 7a823537465bb0c60cada2b76eab28614045617d Mon Sep 17 00:00:00 2001 From: Martin Nygren Date: Fri, 12 Jun 2026 18:13:48 +0100 Subject: [PATCH 4/5] first draft of ai and coding guidelines. --- MODULE.bazel.lock | 2 +- docs/coding_standards_and_ai_advice.md | 31 ++++++++++++++++---------- 2 files changed, 20 insertions(+), 13 deletions(-) diff --git a/MODULE.bazel.lock b/MODULE.bazel.lock index 800cc995..c9c77ee2 100644 --- a/MODULE.bazel.lock +++ b/MODULE.bazel.lock @@ -260,7 +260,7 @@ }, "@@emsdk+//:emscripten_deps.bzl%emscripten_deps": { "general": { - "bzlTransitiveDigest": "Dt5IF0PG0xjU5iMLeU6FQ1/xWvBqUgUognNk3r5pJXY=", + "bzlTransitiveDigest": "reX42Ca3PEP5mFXph0pqMqqqwHJbvykl5X4FHfXD6qg=", "usagesDigest": "lqS0hMGr6MqmX63BGZOskMFcqzqO53K0UlYFxuE3QSU=", "recordedInputs": [ "REPO_MAPPING:bazel_features+,bazel_features_globals bazel_features++version_extension+bazel_features_globals", diff --git a/docs/coding_standards_and_ai_advice.md b/docs/coding_standards_and_ai_advice.md index 8010f7f8..8ede8f56 100644 --- a/docs/coding_standards_and_ai_advice.md +++ b/docs/coding_standards_and_ai_advice.md @@ -2,14 +2,23 @@ Coding agents are becoming increasingly powerful and which tool and model that scores best in test changes if not by the week at least on a monthly basis. These recommendations and instructions for coding were collected in the first quarter of 2026 when the bulk of the work to modernise the codebase for release 3.0.0 was carried out. -Configurations for MCP servers are not included. MCP servers add a lot of power, but can also expose severe vulnerabilities. How they should be deployed is definitely not one size fits all. +Configurations for MCP (Model Content Protocol) servers are not included. MCP servers add a lot of power, but can also expose severe vulnerabilities. How they should be deployed is definitely not one size fits all. + +## Coding Standards + +Keeping a consistent coding style is more important than ever as it helps both humans and coding agents. Preferred styles are document in the `.github/instructions directory`, which is where Github Copilot looks for its permanent instructions. + +1. [C++](../.github/instructions/cpp.instructions.md) +2. [Bazel](../.github/instructions/bazel.instructions.md) +3. [Git](../.github/instructions/git.instructions.md) +4. [GitHub](../.github/instructions/github.instructions.md) ## Recommended tools for coding agents ### clangd https://clangd.llvm.org -Language servers are well known by most integrated development environments but coding agents are typically not able to interact with them directly. There are several MCP wrappers that can surface a language server to a coding agent. This is, however, surfacing raw JSON responses that the coding agent has to interpret and reason around. If - as is highly recommended - you run serena then prefer to let serena handle the integration with language servers. +Language servers are well known to most integrated development environments but coding agents are typically not able to interact with them directly. There are several MCP wrappers that can surface a language server to a coding agent. This is, however, serving raw JSON responses that the coding agent has to interpret and reason around. If - as is highly recommended - you run serena then prefer to let serena handle the integration with language servers. ### Serena https://github.com/oraios/serena @@ -23,22 +32,20 @@ Creates and maintains an index of the codebase. This means that a coding agent o As a side note, I find it interesting that vector embeddings were removed from Claude Code. My amatuer understanding is that Serena tells the agent what the code is doing and code context enginer where the interesting code. This differs from vector embeddnings which tells the coding agent which parts of the codebase looks similar. Knowing that calls to write to the database looks similar is not useful, but the information where they are and what they write is. +## Documentation and code completion -## Coding Standards - -Keeping a consistent coding style is more important than ever as it helps both humans and coding agents. Preferred styles are document in the `.github/instructions directory`, which is where Github Copilot looks for its permanent instructions. +Code documentation for DDS3 is generated through doxygen, which extracts formatted comments from the source code. The +build command -1. [C++](../.github/instructions/cpp.instructions.md) -2. [Bazel](../.github/instructions/bazel.instructions.md) -3. [Git](../.github/instructions/git.instructions.md) -4. [GitHub](../.github/instructions/github.instructions.md) - -## Documentation and code completion +``` +bazelisk build //:doxygen_docs +``` -DDS3 +generates a stack of local html pages. Open `doxygen_output/html/pages.html` to read the documentation. ### Extracting compile_commands.json +Language servers, such as clangd, rely on a file called `compile_commands.json` which contains information about how project artefacts are build. https://github.com/kiron1/bazel-compile-commands https://github.com/hedronvision/bazel-compile-commands-extractor \ No newline at end of file From 88d0558fb01508d2044f7396b88f46139f402f05 Mon Sep 17 00:00:00 2001 From: Martin Nygren Date: Fri, 12 Jun 2026 18:56:59 +0100 Subject: [PATCH 5/5] updates the coding standards and ai advice. --- docs/coding_standards_and_ai_advice.md | 37 +++++++++++++++++--------- 1 file changed, 24 insertions(+), 13 deletions(-) diff --git a/docs/coding_standards_and_ai_advice.md b/docs/coding_standards_and_ai_advice.md index 8ede8f56..9c51378f 100644 --- a/docs/coding_standards_and_ai_advice.md +++ b/docs/coding_standards_and_ai_advice.md @@ -1,51 +1,62 @@ # Coding agents and coding standards -Coding agents are becoming increasingly powerful and which tool and model that scores best in test changes if not by the week at least on a monthly basis. These recommendations and instructions for coding were collected in the first quarter of 2026 when the bulk of the work to modernise the codebase for release 3.0.0 was carried out. +Coding agents are improving quickly, and the best tool or model for a task can change from one month to the next. This note collects the coding guidance and tooling recommendations that were assembled during the first quarter of 2026, when most of the modernisation work for release 3.0.0 was completed. -Configurations for MCP (Model Content Protocol) servers are not included. MCP servers add a lot of power, but can also expose severe vulnerabilities. How they should be deployed is definitely not one size fits all. +This document does not prescribe a specific MCP server setup. MCP servers can be powerful, but they also introduce security risks, so the right deployment strategy depends on the environment. ## Coding Standards -Keeping a consistent coding style is more important than ever as it helps both humans and coding agents. Preferred styles are document in the `.github/instructions directory`, which is where Github Copilot looks for its permanent instructions. +Consistent style matters even more when both humans and coding agents are reading and editing the same code. The preferred conventions are documented in the `.github/instructions` directory, which is where GitHub Copilot looks for its persistent instructions. 1. [C++](../.github/instructions/cpp.instructions.md) 2. [Bazel](../.github/instructions/bazel.instructions.md) 3. [Git](../.github/instructions/git.instructions.md) 4. [GitHub](../.github/instructions/github.instructions.md) -## Recommended tools for coding agents +## Recommended Tools for Coding Agents ### clangd + https://clangd.llvm.org -Language servers are well known to most integrated development environments but coding agents are typically not able to interact with them directly. There are several MCP wrappers that can surface a language server to a coding agent. This is, however, serving raw JSON responses that the coding agent has to interpret and reason around. If - as is highly recommended - you run serena then prefer to let serena handle the integration with language servers. +Language servers are familiar to most IDE users, but coding agents usually cannot interact with them directly. MCP wrappers can expose a language server to an agent, but they often do so by forwarding raw JSON responses that still need to be interpreted. If you also run Serena, prefer to let Serena handle the language-server integration. ### Serena + https://github.com/oraios/serena -Probably the most important tool at the time of writing. Serena provides semantic analysis and instructions to help coding agents stay on target. +Serena is the most useful tool in this workflow. It provides semantic analysis and retrieval features that help coding agents stay focused on the right parts of the codebase and understand the structure of the language they are working in. ### Code Context Engine + https://github.com/elara-labs/code-context-engine -Creates and maintains an index of the codebase. This means that a coding agent often can read only the relevant part of a file instead of searching all the content of several files. +Code Context Engine builds and maintains an index of the codebase, which lets a coding agent inspect the relevant parts of a file without scanning unrelated content across many files. -As a side note, I find it interesting that vector embeddings were removed from Claude Code. My amatuer understanding is that Serena tells the agent what the code is doing and code context enginer where the interesting code. This differs from vector embeddnings which tells the coding agent which parts of the codebase looks similar. Knowing that calls to write to the database looks similar is not useful, but the information where they are and what they write is. +One observation from this tooling landscape is that different systems solve different problems. Serena helps explain what the code is doing, while a code index helps locate where the interesting code lives. That is more useful than simply surfacing syntactically similar code, which is often not enough to guide a change. -## Documentation and code completion +## Documentation and Code Completion -Code documentation for DDS3 is generated through doxygen, which extracts formatted comments from the source code. The -build command +Code documentation for DDS3 is generated with Doxygen, which extracts formatted comments from the source code. Run the following command to generate the local documentation: ``` bazelisk build //:doxygen_docs ``` -generates a stack of local html pages. Open `doxygen_output/html/pages.html` to read the documentation. +The generated HTML pages are available under `doxygen_output/html/`. Open `doxygen_output/html/pages.html` to read the documentation. ### Extracting compile_commands.json -Language servers, such as clangd, rely on a file called `compile_commands.json` which contains information about how project artefacts are build. +Language servers such as clangd rely on a `compile_commands.json` file, which describes how the project is built. + +On macOS or Linux, the following command generates that file when the `bazel-compile-commands` utility is installed: + +``` +bazel-compile-commands //... +``` + https://github.com/kiron1/bazel-compile-commands +An alternative is Hedron Compile Commands, which can be integrated into the Bazel build. It appears to be less actively maintained, but it is still worth knowing about: + https://github.com/hedronvision/bazel-compile-commands-extractor \ No newline at end of file