docs: add AI assistant configuration guidelines by wambitz · Pull Request #44 · wambitz/cpp-template

wambitz · 2026-03-12T01:05:30Z

Summary

This pull request introduces comprehensive documentation for configuring AI code assistants in the project. It adds onboarding guides for both Claude Code and GitHub Copilot, detailing how to set up conventions, build workflows, and code style to ensure generated code matches project standards.

AI assistant configuration documentation:

Added docs/ai-assistant-guide.md, explaining how Claude Code and GitHub Copilot are configured for the project, including file purposes, command workflows, and customization tips.

Copilot instructions and code conventions:

Added .github/copilot-instructions.md, specifying code style, naming conventions, architectural patterns, build/test workflows, and CMake usage guidelines for Copilot-generated code.

Commits

Add onboarding documentation for AI pair programmers:

.github/copilot-instructions.md for GitHub Copilot context
docs/ai-assistant-guide.md explaining all AI config files

Closes #40

Add onboarding documentation for AI pair programmers: - .github/copilot-instructions.md for GitHub Copilot context - docs/ai-assistant-guide.md explaining all AI config files Closes #40

Copilot

Pull request overview

This PR adds onboarding documentation intended to help AI coding assistants (Claude Code and GitHub Copilot) generate code consistent with this C++/CMake template’s conventions.

Changes:

Added docs/ai-assistant-guide.md describing AI-related configuration files and customization guidance.
Added .github/copilot-instructions.md to provide repository-specific Copilot generation instructions (style, architecture, workflows).

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 4 comments.

File	Description
docs/ai-assistant-guide.md	New guide explaining intended Claude Code/Copilot configuration and how to customize it.
.github/copilot-instructions.md	New Copilot repository instructions covering style, project structure, and build/test workflows.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

You can also share your feedback on Copilot code review. Take the survey.

Copilot · 2026-03-12T01:08:47Z

docs/ai-assistant-guide.md

+This project includes configuration for **Claude Code** and **GitHub Copilot**
+so AI tools generate code that matches the project's conventions out of the box.
+
+Think of these files as onboarding documentation for AI pair programmers.
+
+## What's Configured
+
+### Claude Code
+
+| File | Purpose |
+|------|---------|
+| `CLAUDE.md` | Project context: build commands, structure, conventions, anti-patterns |
+| `.claude/settings.json` | Pre-approved commands and auto-format hook |
+| `.claude/commands/*.md` | Custom slash commands (`/build`, `/test`, `/check`, `/add-library`) |


The guide states that Claude Code is configured via .claude/settings.json and .claude/commands/*.md, but the repository currently has no .claude/ directory. Either add these files as part of the configuration, or update this doc to describe them as optional/recommended (so “What’s Configured” matches what’s actually in the repo).

Copilot · 2026-03-12T01:08:47Z

docs/ai-assistant-guide.md

+```json
+{
+  "permissions": {
+    "allow": [
+      "Bash(./scripts/build.sh*)",
+      "Bash(cmake *)",
+      "Bash(ctest *)",
+      ...
+    ]
+  }
+}
+```


The fenced json example isn’t valid JSON because it contains .... If this is intentionally abbreviated, consider changing the fence to a non-JSON language (or jsonc) and/or moving the ellipsis outside the code block so readers can copy/paste a valid settings.json snippet.

Copilot · 2026-03-12T01:08:47Z

docs/ai-assistant-guide.md

+| `.claude/settings.json` | Pre-approved commands and auto-format hook |
+| `.claude/commands/*.md` | Custom slash commands (`/build`, `/test`, `/check`, `/add-library`) |
+
+### GitHub Copilot
+
+| File | Purpose |
+|------|---------|
+| `.github/copilot-instructions.md` | Code style, architecture patterns, naming conventions |
+
+## Claude Code Features Explained
+
+### CLAUDE.md (repository root)
+
+Automatically loaded into every Claude Code conversation. Contains build
+commands, project structure, code conventions, and anti-patterns. Claude uses
+this to generate code that matches `.clang-format` and `.clang-tidy` rules
+without needing to run the formatters.
+
+Supports hierarchical placement — a `CLAUDE.md` in a subdirectory adds context
+for that subtree (e.g., `tests/CLAUDE.md` could add test-specific instructions).
+
+### .claude/settings.json — Pre-approved Commands
+
+Without this file, Claude asks permission every time it runs `cmake`, `ctest`,
+or `./scripts/build.sh`. The settings file pre-approves safe commands:
+
+```json
+{
+  "permissions": {
+    "allow": [
+      "Bash(./scripts/build.sh*)",
+      "Bash(cmake *)",
+      "Bash(ctest *)",
+      ...
+    ]
+  }
+}
+```
+
+This eliminates repetitive permission prompts and makes Claude significantly
+faster to work with. Dangerous commands (`rm -rf /`, `sudo`) are explicitly denied.
+
+Personal overrides go in `.claude/settings.local.json` (gitignored).
+
+### .claude/settings.json — Auto-Format Hook
+
+The `PostToolUse` hook automatically runs `clang-format` on any `.cpp`, `.hpp`,
+or `.h` file that Claude writes or edits. This means Claude's output always
+matches the project's formatting rules — even if Claude's generation doesn't
+perfectly follow `.clang-format`.
+
+### .claude/commands/ — Custom Slash Commands
+
+These are reusable workflows invoked with `/project:command-name`:
+
+| Command | What it does |
+|---------|-------------|
+| `/project:build [config]` | Build the project (default: Debug), run tests |
+| `/project:test [filter]` | Run test suite, optionally filter by name |
+| `/project:check` | Run full CI pipeline locally (format + build + lint + test) |
+| `/project:add-library <name>` | Scaffold a new library target with CMake, source, header, and tests |


The doc mixes two different slash-command names: it says commands are /build//test//check//add-library above, but later describes them as /project:build, /project:test, etc. Please make these consistent so users know the exact invocation syntax.

Copilot · 2026-03-12T01:08:47Z

.github/copilot-instructions.md

+- Use `#pragma once` for header guards
+- New libraries: create `src/<name>/CMakeLists.txt`, add via `add_subdirectory()` in root CMakeLists.txt
+- New tests: create `tests/test_<name>.cpp`, register in `tests/CMakeLists.txt` with `gtest_discover_tests()`
+- Plugin implementations must export `create_plugin()` as `extern "C"`


The plugin factory function name here doesn’t match the template code: src/example_plugin_loader/plugin_loader.cpp looks up register_plugin via dlsym, and src/example_plugin_impl/plugin_impl.cpp exports extern "C" void register_plugin(). Update this instruction to avoid Copilot generating plugins that won’t load (e.g., refer to register_plugin() rather than create_plugin()).

Suggested change

- Plugin implementations must export `create_plugin()` as `extern "C"`

- Plugin implementations must export `register_plugin()` as `extern "C"`

- Fix plugin factory function name: create_plugin → register_plugin (matches actual code in plugin_impl.cpp and plugin_api.hpp) - Mark .claude/settings.json and .claude/commands/ as recommended additions since they don't exist in the repo yet - Fix invalid JSON snippet: use jsonc fence with comment instead of ... - Clarify slash command invocation uses /project: prefix consistently

Copilot

Pull request overview

Copilot reviewed 3 out of 3 changed files in this pull request and generated 3 comments.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

You can also share your feedback on Copilot code review. Take the survey.

Copilot · 2026-03-12T02:36:21Z

docs/ai-assistant-guide.md

+This eliminates repetitive permission prompts and makes Claude significantly
+faster to work with. Dangerous commands (`rm -rf /`, `sudo`) are explicitly denied.
+
+Personal overrides go in `.claude/settings.local.json` (gitignored).


The guide says .claude/settings.local.json is gitignored, but the current .gitignore doesn’t include this path. Either add an ignore entry for .claude/settings.local.json (and possibly .claude/settings.local.*) or adjust the wording to avoid implying it’s already ignored in this repo.

Suggested change

Personal overrides go in `.claude/settings.local.json` (gitignored).

Personal overrides should go in `.claude/settings.local.json`; add this path to your `.gitignore` so local settings aren't committed.

Copilot · 2026-03-12T02:36:22Z

.github/copilot-instructions.md

+- Tests go in `tests/test_<target_name>.cpp` using GoogleTest (GTest)
+- Use `target_include_directories` and `target_link_libraries` with correct CMake visibility keywords (PUBLIC, PRIVATE, INTERFACE)
+- Shared libraries use RPATH (`$ORIGIN/../lib`) for portable deployment
+- Plugins use a C-compatible API with `extern "C"` exported factory functions


This line describes plugins as exporting "factory functions", but the documented/implemented entrypoint is a single register_plugin() symbol (void, no factory/instance semantics). Consider rewording to "exported entrypoint" (or similar) to match the actual plugin ABI and avoid confusion.

Suggested change

- Plugins use a C-compatible API with `extern "C"` exported factory functions

- Plugins use a C-compatible API with `extern "C"` exported entrypoints

Copilot · 2026-03-12T02:36:22Z

.github/copilot-instructions.md

+
+## Build & Test
+
+- Build: `./scripts/build.sh` or `mkdir -p build && cd build && cmake .. && make`


The suggested manual build command (cmake .. && make) doesn’t specify CMAKE_BUILD_TYPE or the install prefix, while ./scripts/build.sh configures Debug and sets CMAKE_INSTALL_PREFIX to install/. To keep onboarding consistent and avoid accidental non-Debug builds, consider updating the command to mirror the script (or reference only ./scripts/build.sh).

Suggested change

- Build: `./scripts/build.sh` or `mkdir -p build && cd build && cmake .. && make`

- Build: `./scripts/build.sh`

- Fix settings.local.json: clarify it's not gitignored yet, advise adding to .gitignore - Fix plugin terminology: "factory functions" → "entrypoints" to match actual register_plugin() ABI - Remove manual cmake build command from copilot instructions to avoid inconsistency with build.sh defaults

Copilot

Pull request overview

Copilot reviewed 3 out of 3 changed files in this pull request and generated 4 comments.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

You can also share your feedback on Copilot code review. Take the survey.

Copilot · 2026-03-12T03:56:41Z

docs/ai-assistant-guide.md

+| File | Purpose |
+|------|---------|
+| `CLAUDE.md` | Project context: build commands, structure, conventions, anti-patterns |
+


The markdown table syntax here starts each row with || (double pipe), which creates an extra empty column and renders incorrectly. Use single leading/trailing pipes (e.g., | File | Purpose |) to make this a valid 2-column table.

Copilot · 2026-03-12T03:56:42Z

docs/ai-assistant-guide.md

+| File | Purpose |
+|------|---------|
+| `.claude/settings.json` | Pre-approved commands and auto-format hook |
+| `.claude/commands/*.md` | Custom slash commands (e.g., `/project:build`, `/project:test`) |
+


This table also uses || at the start of rows, which renders as an extra blank column in Markdown. Switch to the standard | ... | table format so the file/purpose columns display correctly.

Copilot · 2026-03-12T03:56:42Z

docs/ai-assistant-guide.md

+| File | Purpose |
+|------|---------|
+| `.github/copilot-instructions.md` | Code style, architecture patterns, naming conventions |
+


The GitHub Copilot table uses || prefixes as well; Markdown will interpret this as an extra empty column. Use a single | per column boundary so the table renders as intended.

Copilot · 2026-03-12T03:56:42Z

docs/ai-assistant-guide.md

+| Command | What it does |
+|---------|-------------|
+| `/project:build [config]` | Build the project (default: Debug), run tests |
+| `/project:test [filter]` | Run test suite, optionally filter by name |
+| `/project:check` | Run full CI pipeline locally (format + build + lint + test) |
+| `/project:add-library <name>` | Scaffold a new library target with CMake, source, header, and tests |
+


The commands table uses || row prefixes, which will render with an unintended blank first column. Convert this to standard Markdown table syntax (| Command | What it does |, etc.) so the command list displays properly.

docs: add AI assistant configuration guidelines

fd72768

Add onboarding documentation for AI pair programmers: - .github/copilot-instructions.md for GitHub Copilot context - docs/ai-assistant-guide.md explaining all AI config files Closes #40

wambitz self-assigned this Mar 12, 2026

Copilot AI review requested due to automatic review settings March 12, 2026 01:05

wambitz added the documentation Improvements or additions to documentation label Mar 12, 2026

Copilot started reviewing on behalf of wambitz March 12, 2026 01:05 View session

Copilot AI reviewed Mar 12, 2026

View reviewed changes

wambitz requested a review from Copilot March 12, 2026 02:34

Copilot started reviewing on behalf of wambitz March 12, 2026 02:34 View session

Copilot AI reviewed Mar 12, 2026

View reviewed changes

wambitz requested a review from Copilot March 12, 2026 03:54

Copilot started reviewing on behalf of wambitz March 12, 2026 03:54 View session

Copilot AI reviewed Mar 12, 2026

View reviewed changes

wambitz merged commit 3ff3f8d into main Mar 12, 2026
9 checks passed

	- Plugin implementations must export `create_plugin()` as `extern "C"`
	- Plugin implementations must export `register_plugin()` as `extern "C"`

	Personal overrides go in `.claude/settings.local.json` (gitignored).
	Personal overrides should go in `.claude/settings.local.json`; add this path to your `.gitignore` so local settings aren't committed.

	- Plugins use a C-compatible API with `extern "C"` exported factory functions
	- Plugins use a C-compatible API with `extern "C"` exported entrypoints


		## Build & Test

		- Build: `./scripts/build.sh` or `mkdir -p build && cd build && cmake .. && make`

	- Build: `./scripts/build.sh` or `mkdir -p build && cd build && cmake .. && make`
	- Build: `./scripts/build.sh`

Conversation

wambitz commented Mar 12, 2026

Summary

Commits

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI Mar 12, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 12, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 12, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 12, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Copilot AI Mar 12, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 12, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 12, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Copilot AI Mar 12, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 12, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 12, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 12, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants