Adjust tool usage notes (#6853)

Trying to work on some behaviors:

- Using `black` to format Python files (using `pre-commit` makes better
use of allow-listed commands)
- Writing Python code over 80 columns (adding more style notes)
- Running `bazel` (being more emphatic about `bazelisk`, splitting tool
usage out to its own skill to try making clear it's not
toolchain-specific)

Assisted-by: Google Antigravity with Gemini
This commit is contained in:
Jon Ross-Perkins
2026-03-09 14:56:41 +00:00
committed by GitHub
parent cdcd3ab66c
commit 6b2d55d289
4 changed files with 51 additions and 24 deletions
+12 -5
View File
@@ -21,18 +21,25 @@ SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
## Formatting
- **C++**: Always check `clang-format` on C++ files.
- **Bazel**: Use `pre-commit run buildifier --files <file.bzl>` to format
Bazel files.
- **C++**: Use `pre-commit run clang-format --files <file.cpp>` to format C++
files.
- **Carbon**: The toolchain's `format` command doesn't work well right now.
Instead, try to format Carbon code based on other Carbon files and the C++
style.
- **Markdown**: Use `pre-commit run prettier --files <file.md>` to format
markdown files correctly.
markdown files.
- **Python**: Use `pre-commit run black --files <file.py>` to format Python
files.
## Style Guides
Carbon's toolchain uses LLVM-style C++ with some specific conventions.
- **Style Guide**: Follow the
- **C++ style**: Follow the
[Carbon C++ Project Style Guide](/docs/project/cpp_style_guide.md).
- **Markdown style**: Follow the
[Google developer documentation style guide](https://developers.google.com/style).
- **Python style**: Follow the [PEP 8](https://peps.python.org/pep-0008/)
style guide.
- Wrap code and comments to 80 columns.
- Run `pre-commit run flake8 --files <file.py>` to check Python style.
+34
View File
@@ -0,0 +1,34 @@
---
name: Tool usage
description:
Instructions for AI assistants on what tools to use in the carbon-lang
project.
---
# Tool usage
<!--
Part of the Carbon Language project, under the Apache License v2.0 with LLVM
Exceptions. See /LICENSE for license information.
SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
-->
## Bazelisk and Bazel
We use `bazelisk` for build and test.
**IMPORTANT**: AI assistants use `bazelisk` instead of `bazel`.
## Pre-commit
Running `pre-commit` is mandatory. To run it on all files:
```bash
pre-commit run -a
```
To validate a specific list of files:
```bash
pre-commit run --files <files>
```
@@ -41,11 +41,6 @@ SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
- **Iteration**: Prefer iterative algorithms over recursive ones to prevent
stack exhaustion on complex codebases.
## Building and testing
AI assistants should use `bazelisk` instead of `bazel` for build and test
commands, because some AI editors won't see `bazel` aliases.
### Essential commands
- **Test everything**: `bazelisk test //...`
@@ -67,20 +62,6 @@ of expected output.** Use the script:
./toolchain/autoupdate_testdata.py toolchain/check/testdata/my_test.carbon
```
### Pre-commit
Running `pre-commit` is mandatory. To run it on all files:
```bash
pre-commit run -a
```
To validate a specific list of files:
```bash
pre-commit run --files <files>
```
## Debugging and diagnostics
- **Printing to stderr**: Use `llvm::errs() << "debug info\n";`.
+5
View File
@@ -35,6 +35,11 @@ assistant, **read this first** to avoid common pitfalls.
- **[`toolchain/`](toolchain/)**: The C++ implementation of the compiler
(Toolchain).
## Tool usage
See the "Tool usage" skill for instructions on what tools to use in the
carbon-lang project.
## Code style
See the "Code style" skill for instructions on formatting, style guides, and