Skip to content

docs: add AI assistant configuration guidelines #44

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
wambitz merged 3 commits into from
Mar 12, 2026
Merged

docs: add AI assistant configuration guidelines #44

Show file tree
Hide file tree
Changes from 2 commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
fd72768
docs: add AI assistant configuration guidelines
wambitz Mar 12, 2026
6253bdd
docs: address review feedback on AI assistant guidelines
wambitz Mar 12, 2026
b31d7f4
docs: address second round of review feedback
wambitz Mar 12, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
35 changes: 35 additions & 0 deletions .github/copilot-instructions.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,35 @@
# Copilot Instructions

This is a modern C++ project template using CMake >= 3.20 and C++17.

## Code Style

- Follow Google C++ style with 4-space indentation and 100-character column limit
- Variables, locals, and members use `lower_case` naming
- Classes and structs use `CamelCase` naming
- Pointer alignment is left: `int* ptr` not `int *ptr`
- Brace style: K&R (attach opening brace to statement)
- Include sorting: main header first, then system headers, then project headers, separated by blank lines

## Project Architecture

- Each build target has its own subdirectory under `src/` with its own `CMakeLists.txt`
- 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
Copy link

Copilot AI Mar 12, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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 uses AI. Check for mistakes.

## Build & Test

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

Copilot AI Mar 12, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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`

Copilot uses AI. Check for mistakes.
- Test: `cd build && ctest --output-on-failure`
- Format: `./scripts/format.sh`
- Lint: `./scripts/lint.sh` (requires build first for compile_commands.json)

## Conventions

- Always use CMake target properties instead of raw compiler/linker flags
- 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 `register_plugin()` as `extern "C"`
2 changes: 1 addition & 1 deletion CLAUDE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -30,7 +30,7 @@ The template demonstrates four library patterns that build on each other:
- **Interface library** (`example_interface`) — header-only, no compiled output; uses `INTERFACE` visibility so dependents get the include paths automatically
- **Public/Private visibility** (`example_public_private`) — demonstrates how `PUBLIC` includes propagate to dependents while `PRIVATE` includes stay internal

The **plugin system** (`example_plugin_loader` + `example_plugin_impl`) shows runtime loading via `dlopen()`. Plugins implement a C-compatible API defined in `plugin_api.hpp` and must export `create_plugin()` as `extern "C"`. The loader discovers plugin `.so` files via RPATH.
The **plugin system** (`example_plugin_loader` + `example_plugin_impl`) shows runtime loading via `dlopen()`. Plugins implement a C-compatible API defined in `plugin_api.hpp` and must export `register_plugin()` as `extern "C"`. The loader discovers plugin `.so` files via RPATH.

The main executable (`src/main/`) links against all libraries and demonstrates their usage together.

Expand Down
114 changes: 114 additions & 0 deletions docs/ai-assistant-guide.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,114 @@
# AI Assistant Configuration Guide

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 |

Comment on lines +12 to +15
Copy link

Copilot AI Mar 12, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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 uses AI. Check for mistakes.
The following are **recommended additions** (not yet in the repo):

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

Comment on lines +18 to +22
Copy link

Copilot AI Mar 12, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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 uses AI. Check for mistakes.
### GitHub Copilot

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

Comment on lines +25 to +28
Copy link

Copilot AI Mar 12, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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 uses AI. Check for mistakes.
## 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:

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

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).
Copy link

Copilot AI Mar 12, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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 uses AI. Check for mistakes.

### .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 |
Comment on lines +20 to +81
Copy link

Copilot AI Mar 12, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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 uses AI. Check for mistakes.

Comment on lines +76 to +82
Copy link

Copilot AI Mar 12, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copilot uses AI. Check for mistakes.
Commands are invoked with the `/project:` prefix (e.g., `/project:build`).
They accept arguments via `$ARGUMENTS` and are markdown files that tell Claude
what steps to follow — not shell scripts.

### .github/copilot-instructions.md

GitHub Copilot reads this for code generation context. It's intentionally more
concise than `CLAUDE.md` since Copilot uses it as supplementary context alongside
its own code analysis. Focused on naming conventions, architectural patterns,
and build commands.

## How to Customize for Your Project

When you fork this template:

1. **Update `CLAUDE.md`** — Replace example library descriptions with your
actual architecture
2. **Update `.github/copilot-instructions.md`** — Adjust style rules to match
3. **Add slash commands** — Create `.claude/commands/your-workflow.md` for
project-specific workflows
4. **Adjust permissions** — Edit `.claude/settings.json` to pre-approve your
project's build tools

**Tips:**
- Be specific: "Variables use `lower_case`" beats "write clean code"
- Document anti-patterns: "do not use X" prevents common AI mistakes
- Keep `CLAUDE.md` under 200 lines — longer files waste context and reduce adherence
- Test your instructions: ask the AI to generate a file and verify it follows conventions

## Further Reading

- [Claude Code documentation](https://docs.anthropic.com/en/docs/claude-code)
- [GitHub Copilot custom instructions](https://docs.github.com/en/copilot/customizing-copilot/adding-repository-custom-instructions-for-github-copilot)
Loading