Skip to content

Commit fd72768

Browse files
wambitzwambitz
committed
docs: add AI assistant configuration guidelines
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
1 parent b6568b6 commit fd72768

2 files changed

Lines changed: 143 additions & 0 deletions

File tree

‎.github/copilot-instructions.md‎

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
# Copilot Instructions
2+
3+
This is a modern C++ project template using CMake >= 3.20 and C++17.
4+
5+
## Code Style
6+
7+
- Follow Google C++ style with 4-space indentation and 100-character column limit
8+
- Variables, locals, and members use `lower_case` naming
9+
- Classes and structs use `CamelCase` naming
10+
- Pointer alignment is left: `int* ptr` not `int *ptr`
11+
- Brace style: K&R (attach opening brace to statement)
12+
- Include sorting: main header first, then system headers, then project headers, separated by blank lines
13+
14+
## Project Architecture
15+
16+
- Each build target has its own subdirectory under `src/` with its own `CMakeLists.txt`
17+
- Tests go in `tests/test_<target_name>.cpp` using GoogleTest (GTest)
18+
- Use `target_include_directories` and `target_link_libraries` with correct CMake visibility keywords (PUBLIC, PRIVATE, INTERFACE)
19+
- Shared libraries use RPATH (`$ORIGIN/../lib`) for portable deployment
20+
- Plugins use a C-compatible API with `extern "C"` exported factory functions
21+
22+
## Build & Test
23+
24+
- Build: `./scripts/build.sh` or `mkdir -p build && cd build && cmake .. && make`
25+
- Test: `cd build && ctest --output-on-failure`
26+
- Format: `./scripts/format.sh`
27+
- Lint: `./scripts/lint.sh` (requires build first for compile_commands.json)
28+
29+
## Conventions
30+
31+
- Always use CMake target properties instead of raw compiler/linker flags
32+
- Use `#pragma once` for header guards
33+
- New libraries: create `src/<name>/CMakeLists.txt`, add via `add_subdirectory()` in root CMakeLists.txt
34+
- New tests: create `tests/test_<name>.cpp`, register in `tests/CMakeLists.txt` with `gtest_discover_tests()`
35+
- Plugin implementations must export `create_plugin()` as `extern "C"`

‎docs/ai-assistant-guide.md‎

Lines changed: 108 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,108 @@
1+
# AI Assistant Configuration Guide
2+
3+
This project includes configuration for **Claude Code** and **GitHub Copilot**
4+
so AI tools generate code that matches the project's conventions out of the box.
5+
6+
Think of these files as onboarding documentation for AI pair programmers.
7+
8+
## What's Configured
9+
10+
### Claude Code
11+
12+
| File | Purpose |
13+
|------|---------|
14+
| `CLAUDE.md` | Project context: build commands, structure, conventions, anti-patterns |
15+
| `.claude/settings.json` | Pre-approved commands and auto-format hook |
16+
| `.claude/commands/*.md` | Custom slash commands (`/build`, `/test`, `/check`, `/add-library`) |
17+
18+
### GitHub Copilot
19+
20+
| File | Purpose |
21+
|------|---------|
22+
| `.github/copilot-instructions.md` | Code style, architecture patterns, naming conventions |
23+
24+
## Claude Code Features Explained
25+
26+
### CLAUDE.md (repository root)
27+
28+
Automatically loaded into every Claude Code conversation. Contains build
29+
commands, project structure, code conventions, and anti-patterns. Claude uses
30+
this to generate code that matches `.clang-format` and `.clang-tidy` rules
31+
without needing to run the formatters.
32+
33+
Supports hierarchical placement — a `CLAUDE.md` in a subdirectory adds context
34+
for that subtree (e.g., `tests/CLAUDE.md` could add test-specific instructions).
35+
36+
### .claude/settings.json — Pre-approved Commands
37+
38+
Without this file, Claude asks permission every time it runs `cmake`, `ctest`,
39+
or `./scripts/build.sh`. The settings file pre-approves safe commands:
40+
41+
```json
42+
{
43+
"permissions": {
44+
"allow": [
45+
"Bash(./scripts/build.sh*)",
46+
"Bash(cmake *)",
47+
"Bash(ctest *)",
48+
...
49+
]
50+
}
51+
}
52+
```
53+
54+
This eliminates repetitive permission prompts and makes Claude significantly
55+
faster to work with. Dangerous commands (`rm -rf /`, `sudo`) are explicitly denied.
56+
57+
Personal overrides go in `.claude/settings.local.json` (gitignored).
58+
59+
### .claude/settings.json — Auto-Format Hook
60+
61+
The `PostToolUse` hook automatically runs `clang-format` on any `.cpp`, `.hpp`,
62+
or `.h` file that Claude writes or edits. This means Claude's output always
63+
matches the project's formatting rules — even if Claude's generation doesn't
64+
perfectly follow `.clang-format`.
65+
66+
### .claude/commands/ — Custom Slash Commands
67+
68+
These are reusable workflows invoked with `/project:command-name`:
69+
70+
| Command | What it does |
71+
|---------|-------------|
72+
| `/project:build [config]` | Build the project (default: Debug), run tests |
73+
| `/project:test [filter]` | Run test suite, optionally filter by name |
74+
| `/project:check` | Run full CI pipeline locally (format + build + lint + test) |
75+
| `/project:add-library <name>` | Scaffold a new library target with CMake, source, header, and tests |
76+
77+
Commands accept arguments via `$ARGUMENTS`. They're markdown files that tell
78+
Claude what steps to follow — not shell scripts.
79+
80+
### .github/copilot-instructions.md
81+
82+
GitHub Copilot reads this for code generation context. It's intentionally more
83+
concise than `CLAUDE.md` since Copilot uses it as supplementary context alongside
84+
its own code analysis. Focused on naming conventions, architectural patterns,
85+
and build commands.
86+
87+
## How to Customize for Your Project
88+
89+
When you fork this template:
90+
91+
1. **Update `CLAUDE.md`** — Replace example library descriptions with your
92+
actual architecture
93+
2. **Update `.github/copilot-instructions.md`** — Adjust style rules to match
94+
3. **Add slash commands** — Create `.claude/commands/your-workflow.md` for
95+
project-specific workflows
96+
4. **Adjust permissions** — Edit `.claude/settings.json` to pre-approve your
97+
project's build tools
98+
99+
**Tips:**
100+
- Be specific: "Variables use `lower_case`" beats "write clean code"
101+
- Document anti-patterns: "do not use X" prevents common AI mistakes
102+
- Keep `CLAUDE.md` under 200 lines — longer files waste context and reduce adherence
103+
- Test your instructions: ask the AI to generate a file and verify it follows conventions
104+
105+
## Further Reading
106+
107+
- [Claude Code documentation](https://docs.anthropic.com/en/docs/claude-code)
108+
- [GitHub Copilot custom instructions](https://docs.github.com/en/copilot/customizing-copilot/adding-repository-custom-instructions-for-github-copilot)

0 commit comments

Comments
 (0)