feat(skills): add coding-dev.md and per-language rules under code-languages/
Generic coding rules and preferences distilled from existing agent rule files, project AGENTS.md/.rules, and saved memories: - strictness maximal; suppressions must be reported to the user - never filter build/lint/test output through grep/tail/head - reuse > fork > self-implement; generic code becomes its own package - 1000-line file / 100-line function limits, split by concern - regression test every fixed bug; never test against real user data - events over polling; scope discipline; honest reporting Per-language: rust, js-typescript, bash, python, go, csharp-dotnet, c-cpp. Each extends coding-dev.md rather than repeating it. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This commit is contained in:
BluscreamandClaude Opus 5 committed
1 parent
ba95f171b2
commit
57968904bf
9 files changed
+1499
-1
No files matched your search
@@ -6,7 +6,36 @@ A collection of public, reusable agent skills, cheatsheets, and operational work
|
||||
|
||||
## 📂 Skills Index
|
||||
|
||||
*(Public skills will be added here as generic, open workflows)*
|
||||
| Skill File | Scope / Topics Covered |
|
||||
| :--- | :--- |
|
||||
| **[`coding-dev.md`](./coding-dev.md)** | Standing rules for all code work: maximum linter/compiler strictness, never filtering build output, reuse-before-reinvent dependency ordering, file/function size limits, test & regression discipline, verification gates, scope control, commit hygiene, and honest reporting. |
|
||||
|
||||
### 🔤 Per-Language Rules ([`code-languages/`](./code-languages/))
|
||||
|
||||
| Language | Skill File | Highlights |
|
||||
| :--- | :--- | :--- |
|
||||
| **Rust** | [`rust.md`](./code-languages/rust.md) | `--workspace` clippy gate, `[workspace.lints]` single source of truth, no `unwrap`/`unsafe`, core-crate split |
|
||||
| **TypeScript / JavaScript** | [`js-typescript.md`](./code-languages/js-typescript.md) | TS > JSDoc > plain JS, banned constructs table, React & hooks rules, resource lifecycle, sandbox boundaries |
|
||||
| **Bash / Shell** | [`bash.md`](./code-languages/bash.md) | `set -euo pipefail`, shellcheck, no wait loops, destructive-command guards, build-gate structure |
|
||||
| **Python** | [`python.md`](./code-languages/python.md) | `mypy --strict`, broad ruff rule set, asyncio task discipline, rate-limit queueing |
|
||||
| **Go** | [`go.md`](./code-languages/go.md) | strict `golangci-lint` set, concrete types over `interface{}`, context everywhere, CGO-free static builds |
|
||||
| **C# / .NET** | [`csharp-dotnet.md`](./code-languages/csharp-dotnet.md) | `TreatWarningsAsErrors`, nullable enabled, no `.Result`, trimming/single-file publish caveats, SDK shims |
|
||||
| **C / C++** | [`c-cpp.md`](./code-languages/c-cpp.md) | full warning set + `-Werror`, sanitizers, RAII/Rule of Zero, target-based CMake, FFI ownership |
|
||||
|
||||
Each language file extends `coding-dev.md` rather than repeating it. A project's own
|
||||
`AGENTS.md` / `CLAUDE.md` / `.rules` always overrides both.
|
||||
|
||||
---
|
||||
|
||||
## ✍️ Skill Document Conventions
|
||||
|
||||
Skills in this repo follow the same structure as the private counterpart repo, so agents can load either interchangeably:
|
||||
|
||||
1. **YAML frontmatter** with `name` (kebab-case, matching the filename) and a `description` starting with *"Use this skill when …"* — the description is what an agent matches against to decide relevance, so it must enumerate concrete triggers.
|
||||
2. **Numbered `##` sections**, sequential and unique, ending with a **Related Skills** section that cross-links sibling documents.
|
||||
3. **CLI discovery over enumeration** — document the *non-obvious* workflows, gotchas, and constraints. For the routine surface, point at `<tool> --help` rather than transcribing flag lists that will go stale.
|
||||
4. **No secrets inline** — reference the environment file that holds them (e.g. `~/.config/environment.d/…`), never the values themselves.
|
||||
5. **Verify before documenting** — confirm hostnames, container names, and versions against the live system rather than carrying forward stale claims.
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -0,0 +1,172 @@
|
||||
---
|
||||
name: bash
|
||||
description: >-
|
||||
Use this skill when writing or modifying Bash/shell scripts, build pipelines, release
|
||||
scripts, or when running shell commands as an agent. Covers strict mode, shellcheck,
|
||||
quoting, the no-wait-loops rule, build-script structure, and destructive-command safety.
|
||||
---
|
||||
|
||||
# Bash / Shell — Rules & Preferences
|
||||
|
||||
Extends [`../coding-dev.md`](../coding-dev.md). Everything there applies; this adds shell specifics.
|
||||
|
||||
Bash is for **orchestration** — sequencing tools, wiring a build pipeline, gluing CLIs.
|
||||
Once a script grows real data structures, arithmetic, or parsing, it wants to be Python or
|
||||
a compiled tool instead.
|
||||
|
||||
---
|
||||
|
||||
## 1. Strict Mode & Linting
|
||||
|
||||
Every script starts with:
|
||||
|
||||
```bash
|
||||
#!/usr/bin/env bash
|
||||
set -euo pipefail
|
||||
IFS=$'\n\t'
|
||||
```
|
||||
|
||||
- `-e` exit on error, `-u` error on unset variable, `-o pipefail` so a failure mid-pipe is
|
||||
not masked by a successful final command.
|
||||
- **`shellcheck` must be clean** and belongs in the build gate. Do not silence a finding with
|
||||
a `# shellcheck disable=` without a comment saying why.
|
||||
- Format with `shfmt`.
|
||||
|
||||
> [!IMPORTANT]
|
||||
> `set -e` does **not** fire inside `if`, `&&`, `||`, or command substitution used in a
|
||||
> condition. Do not assume a failing command inside those aborts the script — check
|
||||
> explicitly where it matters.
|
||||
|
||||
---
|
||||
|
||||
## 2. Quoting & Expansion
|
||||
|
||||
- **Quote every expansion**: `"$var"`, `"${arr[@]}"`, `"$(cmd)"`. Unquoted expansion word-splits
|
||||
and glob-expands, which is how a path with a space becomes two broken arguments.
|
||||
- `"${var:-default}"` for defaults; `"${var:?message}"` for required values.
|
||||
- Use arrays for argument lists — never build a command as a string and `eval` it.
|
||||
- `[[ ]]` over `[ ]`. `$(…)` over backticks.
|
||||
- `local` every variable inside a function.
|
||||
- `printf` over `echo` for anything with escapes or leading dashes.
|
||||
|
||||
---
|
||||
|
||||
## 3. Never Write Wait Loops
|
||||
|
||||
> [!CAUTION]
|
||||
> **Do not write `until <check>; do sleep 2; done` or `while ! <check>; do sleep …; done`.**
|
||||
> They hang the terminal, and the only way out is an interrupt.
|
||||
|
||||
To wait for something:
|
||||
- Run the work in the **background** and wait for its completion signal.
|
||||
- To check external state, **take a single sample per invocation** rather than looping.
|
||||
- If a tool has a real blocking wait (`--wait`, `wait-for`, `systemctl is-active --wait`),
|
||||
use that instead of polling around it.
|
||||
|
||||
This mirrors the general events-over-polling preference: prefer a notification to a loop.
|
||||
|
||||
---
|
||||
|
||||
## 4. Never Filter Build Output
|
||||
|
||||
Repeating the global rule because shell is where it gets violated:
|
||||
|
||||
```bash
|
||||
# WRONG
|
||||
cargo build 2>&1 | grep -E "error|warning"
|
||||
npm run build | tail -20
|
||||
|
||||
# RIGHT
|
||||
cargo build
|
||||
npm run build
|
||||
```
|
||||
|
||||
Tee to a log if you need a copy — `cmd 2>&1 | tee build.log` preserves the full output — but
|
||||
never `grep`/`head`/`tail` it away. Narrow the command instead when output is genuinely huge.
|
||||
|
||||
---
|
||||
|
||||
## 5. Destructive Commands
|
||||
|
||||
- **Look at the target before deleting or overwriting it.** `ls` it, `stat` it, read it.
|
||||
- Never `rm -rf "$VAR"` without first asserting `$VAR` is non-empty and is what you think:
|
||||
```bash
|
||||
[[ -n "${BUILD_DIR:-}" && -d "$BUILD_DIR" ]] || { echo "refusing: BUILD_DIR unset" >&2; exit 1; }
|
||||
```
|
||||
- **A shared output directory belongs to nobody.** If two scripts write to `dist/`, neither
|
||||
may `rm -rf` it — each cleans only its own outputs.
|
||||
- Write scratch files to a `mktemp -d` and trap cleanup:
|
||||
```bash
|
||||
tmp="$(mktemp -d)"; trap 'rm -rf "$tmp"' EXIT
|
||||
```
|
||||
- Prefer a `--dry-run` flag on anything that deploys, releases, or deletes — and implement it
|
||||
honestly.
|
||||
|
||||
### `pgrep -f` matches its own shell
|
||||
|
||||
> [!WARNING]
|
||||
> The command line containing the pattern **is itself a process**, so `pgrep -f foo.conf`
|
||||
> matches the shell running it. Piping that into `kill` kills the running script — which reads
|
||||
> exactly like "the thing I was testing never happened".
|
||||
>
|
||||
> Write the pattern so it cannot match itself: `pgrep -f 'my[a]pp\.conf'`
|
||||
|
||||
---
|
||||
|
||||
## 6. Build Script Structure
|
||||
|
||||
A build script is the project's **quality gate**, and it should be exhaustive enough to catch
|
||||
mistakes before a human does.
|
||||
|
||||
- **Fixed action order regardless of flag order**, with any failure aborting the rest:
|
||||
```
|
||||
bump → lint → build → artifacts → stop → deploy → start → commit → push → release
|
||||
```
|
||||
- **A skipped test fails the gate.** Never let a skip report green.
|
||||
- **Print a summary with numbers**, not just a verdict — counts of warnings, suppressions, and
|
||||
file-size violations. A suppression count that has grown is worth seeing even on a pass.
|
||||
- Keep per-step logs in a known directory so a failure can be read after the fact.
|
||||
- **Never bypass a failed gate** by copying a binary or running the install step by hand. Fix
|
||||
the failing step; do not weaken the check to make it pass.
|
||||
- Support `--dry-run` for the full release path.
|
||||
- **Throttle heavy builds.** Detect when something latency-sensitive is running and drop to
|
||||
half the cores at `nice -n 10`, announcing that it did so. Provide an override env var.
|
||||
|
||||
---
|
||||
|
||||
## 7. Paths & Portability
|
||||
|
||||
- Resolve the script's own directory rather than assuming the caller's `cwd`:
|
||||
```bash
|
||||
script_dir="$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd)"
|
||||
```
|
||||
- Prefer absolute paths in anything non-interactive.
|
||||
- **Entering a container resets the working directory** — chain `cd` inside the same command
|
||||
string: `container-run -- bash -c "cd /path && make"`.
|
||||
- Don't hardcode `/tmp` when the content must survive a cleanup; `/var/tmp` persists longer.
|
||||
- `command -v tool >/dev/null || { echo "tool required" >&2; exit 1; }` before using an
|
||||
optional dependency. **A silently skipped step is worse than a failure** — a packaging step
|
||||
that quietly skips when its tool is missing will ship an incomplete release.
|
||||
|
||||
---
|
||||
|
||||
## 8. Secrets
|
||||
|
||||
- Read secrets from an environment file or secret store; **never** inline them in a script.
|
||||
- Never `echo` a secret, and never pass one as a command-line argument — argv is world-readable
|
||||
in the process table. Use an env var or stdin.
|
||||
- Never commit a file containing real credentials; commit an example with empty values.
|
||||
|
||||
---
|
||||
|
||||
## 9. Script Placement
|
||||
|
||||
Standalone utility scripts belong in a **dedicated scripts directory**, symlinked into `PATH`
|
||||
rather than copied there. Never write a loose script directly into `~/.local/bin` or another
|
||||
`PATH` directory — the source of truth should be one versioned location.
|
||||
|
||||
---
|
||||
|
||||
## 10. Related
|
||||
- [`../coding-dev.md`](../coding-dev.md) — the general rules this extends.
|
||||
- [`python.md`](./python.md) — where a shell script should have become a Python script.
|
||||
@@ -0,0 +1,153 @@
|
||||
---
|
||||
name: c-cpp
|
||||
description: >-
|
||||
Use this skill when writing, building, or debugging C or C++ — including compiler warning
|
||||
configuration, sanitizers, modern C++ resource management, build systems (CMake/Meson),
|
||||
32-bit/cross builds, and FFI boundaries exposed to other languages.
|
||||
---
|
||||
|
||||
# C / C++ — Rules & Preferences
|
||||
|
||||
Extends [`../coding-dev.md`](../coding-dev.md). Everything there applies; this adds C/C++ specifics.
|
||||
|
||||
C and C++ are for the cases with no better option: existing codebases, hard real-time paths,
|
||||
and FFI boundaries. **For new standalone work, prefer Rust** — the memory-safety guarantees
|
||||
are worth more than the familiarity.
|
||||
|
||||
---
|
||||
|
||||
## 1. Warnings — Everything On, Errors
|
||||
|
||||
```cmake
|
||||
target_compile_options(mytarget PRIVATE
|
||||
-Wall -Wextra -Wpedantic -Werror
|
||||
-Wshadow -Wconversion -Wsign-conversion
|
||||
-Wnon-virtual-dtor -Wold-style-cast -Wcast-align
|
||||
-Wunused -Woverloaded-virtual -Wdouble-promotion
|
||||
-Wformat=2 -Wnull-dereference -Wimplicit-fallthrough
|
||||
)
|
||||
```
|
||||
|
||||
- **`-Werror` in the build gate.** `-Wconversion` and `-Wshadow` are noisy on first contact and
|
||||
catch real bugs — do not drop them because a legacy file complains; fix the file or scope the
|
||||
suppression to it.
|
||||
- Run **both** GCC and Clang where possible; each diagnoses things the other misses.
|
||||
- `clang-tidy` with `bugprone-*`, `cert-*`, `performance-*`, `modernize-*`.
|
||||
- `clang-format` with a committed `.clang-format`. No hand-formatting.
|
||||
|
||||
---
|
||||
|
||||
## 2. Sanitizers — Use Them
|
||||
|
||||
```bash
|
||||
cmake -DCMAKE_BUILD_TYPE=Debug \
|
||||
-DCMAKE_CXX_FLAGS="-fsanitize=address,undefined -fno-omit-frame-pointer"
|
||||
```
|
||||
|
||||
- **ASan + UBSan on every debug/test build.** They find the bugs that warnings cannot.
|
||||
- TSan for anything threaded (separate build — it is incompatible with ASan).
|
||||
- Valgrind when a sanitizer build is not possible.
|
||||
- **A sanitizer finding is a bug, not noise.** Fix it.
|
||||
|
||||
---
|
||||
|
||||
## 3. Resource Management (C++)
|
||||
|
||||
- **RAII for everything.** Every raw `new`/`delete`, `malloc`/`free`, `fopen`/`fclose`, and
|
||||
native handle pair is a leak waiting for an early return or a throw.
|
||||
- `std::unique_ptr` by default; `std::shared_ptr` only where ownership is genuinely shared.
|
||||
`std::weak_ptr` to break cycles.
|
||||
- **No owning raw pointers.** A raw pointer or reference in a signature means "borrowed,
|
||||
non-owning, outlives the call".
|
||||
- `std::string_view` / `std::span` for non-owning views — and never return one that outlives
|
||||
its backing storage.
|
||||
- **The Rule of Zero**: design so no destructor, copy, or move needs writing. If you must write
|
||||
one, write all five.
|
||||
- `constexpr`, `const`, and `noexcept` wherever they hold. `[[nodiscard]]` on anything whose
|
||||
return value must not be dropped.
|
||||
|
||||
---
|
||||
|
||||
## 4. C Specifics
|
||||
|
||||
- C17 or later unless the target forbids it.
|
||||
- **Check every allocation and every return value.** In C, unchecked returns are the primary
|
||||
bug source.
|
||||
- Fixed-width types from `<stdint.h>` (`uint32_t`), never bare `int` for anything with a
|
||||
defined width on the wire.
|
||||
- Always the bounded string functions (`snprintf`, `strncpy` with explicit termination); never
|
||||
`strcpy`, `sprintf`, `gets`.
|
||||
- `static` on every function and global not exported from the translation unit.
|
||||
- Prefer a struct-and-functions module boundary with an opaque pointer over exposing layout.
|
||||
|
||||
---
|
||||
|
||||
## 5. Build Systems
|
||||
|
||||
- **CMake** (3.20+, target-based) or **Meson** for new projects. Never a hand-written Makefile
|
||||
for anything non-trivial.
|
||||
- Target-based CMake only: `target_link_libraries`, `target_include_directories`,
|
||||
`target_compile_options`. **No directory-level `include_directories` or global
|
||||
`CMAKE_CXX_FLAGS` mutation.**
|
||||
- `PRIVATE` / `PUBLIC` / `INTERFACE` chosen deliberately — this is what keeps include leaks out
|
||||
of dependents.
|
||||
- **Register every new source file with the build system** in the same commit that adds it. A
|
||||
source file the build never compiles will sit there looking correct while every edit to it
|
||||
does nothing.
|
||||
- Vendor dependencies with `FetchContent` or submodules; document which and why.
|
||||
|
||||
---
|
||||
|
||||
## 6. Cross & Multi-Arch Builds
|
||||
|
||||
- Keep 32-bit and 64-bit outputs in **separate build directories**; never reuse one.
|
||||
- **A component built for one architecture cannot load one built for another.** An
|
||||
`ELFCLASS64` / `ELFCLASS32` error means a loader path is reaching the wrong build — check the
|
||||
library search path, not the code.
|
||||
- When a build must match an already-installed runtime's version, **pin it explicitly** and
|
||||
note the constraint. A silently mismatched pair fails at load time with a message that
|
||||
points nowhere useful.
|
||||
- Record the exact toolchain and container used for a cross build. "It built on my machine" is
|
||||
not reproducible for native code.
|
||||
|
||||
---
|
||||
|
||||
## 7. FFI Boundaries
|
||||
|
||||
When exposing C/C++ to another language:
|
||||
|
||||
- `extern "C"` on the boundary, with a hand-written, stable, documented header.
|
||||
- **Ownership across the boundary must be explicit** — who allocates, who frees, and with which
|
||||
function. Provide a matching `free` for every allocation you hand out.
|
||||
- **Never let an exception cross an `extern "C"` boundary.** Catch everything at the edge and
|
||||
convert to an error code.
|
||||
- Bindings generated by a tool (`bindgen`, etc.) are regenerated, never hand-edited.
|
||||
- On the consuming side, keep all `unsafe`/unmanaged interop in **one thin wrapper module**
|
||||
that exposes a safe API — never scattered through call sites.
|
||||
|
||||
> [!WARNING]
|
||||
> **Binding crates/packages that reach into a library's struct fields break when that library
|
||||
> makes the struct opaque.** Pin to a binding version that matches the installed library
|
||||
> generation, and note the constraint where someone will read it before bumping.
|
||||
|
||||
---
|
||||
|
||||
## 8. Testing & Debugging
|
||||
|
||||
- GoogleTest or Catch2; CTest integration so `ctest` runs the suite.
|
||||
- **Regression test every fixed bug.**
|
||||
- Debug builds keep frame pointers (`-fno-omit-frame-pointer`) so stack traces are usable.
|
||||
- `-g` even in release builds; ship separate debug symbols rather than none.
|
||||
- **Record dead ends in the project's notes**, especially for native debugging — the
|
||||
investigation that ruled something out is expensive and will otherwise be repeated. Note
|
||||
what did *not* work alongside what did.
|
||||
- When a binary search through a packed/embedded blob finds nothing, that is not evidence the
|
||||
content is absent — packed asset formats defeat naive string searches. Re-check without
|
||||
anchoring before concluding.
|
||||
|
||||
---
|
||||
|
||||
## 9. Related
|
||||
- [`../coding-dev.md`](../coding-dev.md) — the general rules this extends.
|
||||
- [`rust.md`](./rust.md) — the preferred language for new native work, and the usual consumer
|
||||
of these FFI boundaries.
|
||||
@@ -0,0 +1,151 @@
|
||||
---
|
||||
name: csharp-dotnet
|
||||
description: >-
|
||||
Use this skill when writing, building, or releasing C# / .NET code — including nullable
|
||||
reference types, warnings-as-errors, analyzer configuration, async/await rules, trimming
|
||||
and single-file publishing, and multi-generation SDK compatibility shims.
|
||||
---
|
||||
|
||||
# C# / .NET — Rules & Preferences
|
||||
|
||||
Extends [`../coding-dev.md`](../coding-dev.md). Everything there applies; this adds .NET specifics.
|
||||
|
||||
---
|
||||
|
||||
## 1. Project Settings — Strict By Default
|
||||
|
||||
```xml
|
||||
<PropertyGroup>
|
||||
<Nullable>enable</Nullable>
|
||||
<TreatWarningsAsErrors>true</TreatWarningsAsErrors>
|
||||
<EnforceCodeStyleInBuild>true</EnforceCodeStyleInBuild>
|
||||
<AnalysisLevel>latest-all</AnalysisLevel>
|
||||
<ImplicitUsings>enable</ImplicitUsings>
|
||||
<LangVersion>latest</LangVersion>
|
||||
</PropertyGroup>
|
||||
```
|
||||
|
||||
Put these in a `Directory.Build.props` at the repository root so every project inherits them
|
||||
and none can quietly drift.
|
||||
|
||||
**Every build carries `-warnaserror`:**
|
||||
|
||||
```bash
|
||||
dotnet build MySolution.sln -warnaserror
|
||||
```
|
||||
|
||||
- **Nullable warnings are real bugs.** Never silence one with `!` (null-forgiving) — narrow
|
||||
the type or fix the contract. `!` is an assertion, and an assertion you cannot prove is a
|
||||
future `NullReferenceException`.
|
||||
- Never blanket-disable an analyzer. If a rule is genuinely wrong for the codebase, configure
|
||||
it once in `.editorconfig` with a comment.
|
||||
|
||||
---
|
||||
|
||||
## 2. Async
|
||||
|
||||
- **`async`/`await` throughout; never `.Result` or `.Wait()`** — both deadlock in any context
|
||||
with a synchronization context, and turn an exception into an `AggregateException`.
|
||||
- `async Task`, never `async void`, except for genuine event handlers.
|
||||
- `ConfigureAwait(false)` in library code; not needed in app code on modern hosts.
|
||||
- Accept a `CancellationToken` on every async public method and actually honor it.
|
||||
- `IAsyncEnumerable<T>` for streaming rather than materializing a whole collection.
|
||||
- **Events over polling** — subscribe to the framework's event/observable API; don't run a
|
||||
timer loop. (Global rule; it applies fully here.)
|
||||
|
||||
---
|
||||
|
||||
## 3. Errors, Disposal & Logging
|
||||
|
||||
- Specific exception types; never `catch (Exception)` without a reason and a log.
|
||||
- **Never an empty catch block.**
|
||||
- `using`/`await using` declarations for everything `IDisposable`/`IAsyncDisposable`.
|
||||
Disposal is not optional for streams, HTTP handlers, DB contexts, or native handles.
|
||||
- **One static `HttpClient` (or `IHttpClientFactory`)** — a per-request `HttpClient` exhausts
|
||||
sockets under load.
|
||||
- Structured logging (Serilog or `ILogger<T>`) with message templates, not string interpolation:
|
||||
`logger.LogInformation("Loaded {Count} items", count)` — the template is what makes the log
|
||||
queryable.
|
||||
- **Never log secrets.**
|
||||
|
||||
---
|
||||
|
||||
## 4. Style
|
||||
|
||||
- File-scoped namespaces, `var` for obvious types, target-typed `new()`.
|
||||
- `record` for immutable value types; `readonly struct` for small value types.
|
||||
- Pattern matching and switch expressions over `if`/`else` ladders.
|
||||
- `IReadOnlyList<T>` / `IReadOnlyDictionary<K,V>` in public signatures returning collections.
|
||||
- `internal` by default; `public` only for genuine API surface.
|
||||
- File and function size limits from the general rules apply.
|
||||
- `dotnet format` before committing.
|
||||
|
||||
---
|
||||
|
||||
## 5. Publishing — Trimming & Single File
|
||||
|
||||
> [!IMPORTANT]
|
||||
> **The trimmer only runs on a Release/trimmed/single-file publish.** A Debug build cannot
|
||||
> reproduce the trimmer dropping a type that only reflection reaches. If your release pipeline
|
||||
> ships trimmed binaries, the publish step is the **only** one that exercises the trimmer —
|
||||
> so it must run before release, not after.
|
||||
|
||||
- Annotate reflection-reached types with `[DynamicallyAccessedMembers]` or a
|
||||
`TrimmerRootDescriptor`, and **smoke-test the published binary**, not just the build.
|
||||
- Enable `<IsTrimmable>` per library deliberately; blanket trimming of a plugin host breaks
|
||||
plugin loading.
|
||||
- **A release is a fixed, complete set of assets.** Define what that set is, and have the
|
||||
release step verify it is complete rather than trusting whatever happens to be in the output
|
||||
directory. A packaging tool that silently skips a step when a dependency is missing will
|
||||
otherwise ship a release with a missing platform.
|
||||
|
||||
---
|
||||
|
||||
## 6. Multi-Generation SDK Compatibility
|
||||
|
||||
When targeting several generations of a host SDK whose API changed shape (a class becoming an
|
||||
interface, a type being renamed):
|
||||
|
||||
- **All compatibility code lives in dedicated shim files** — e.g. `GlobalUsings.cs` and
|
||||
`<Host>SdkShims.cs`. Never scatter `#if` directives through feature code.
|
||||
- Select the target with an MSBuild property so the build is explicit about which generation
|
||||
it produced:
|
||||
```bash
|
||||
dotnet build MyModules.csproj -c Release -p:HostTarget=stable
|
||||
dotnet build MyModules.csproj -c Release -p:HostTarget=beta
|
||||
```
|
||||
- Document the differences between generations in the project's agent/contributor file —
|
||||
which types changed, and which direction each shim adapts.
|
||||
- Keep a local package feed for SDK versions not published to the public registry, and script
|
||||
the packing step rather than doing it by hand.
|
||||
|
||||
---
|
||||
|
||||
## 7. Testing
|
||||
|
||||
- xUnit (or the project's existing framework); `FluentAssertions` for readable assertions.
|
||||
- **Regression test every fixed bug.**
|
||||
- Inject abstractions for filesystem, clock, and network so they can be faked — do not reach
|
||||
for a static.
|
||||
- **Never test mutations against real user profiles, real config directories, or live
|
||||
services.** Fixtures and injected backends only.
|
||||
- Test the **published** artifact for anything involving trimming, single-file packing, or
|
||||
native dependencies — the assembly that passed unit tests is not the one you shipped.
|
||||
|
||||
---
|
||||
|
||||
## 8. Toolchain Notes
|
||||
|
||||
- When the SDK is not installed on the host (immutable OS, mismatched glibc), build inside the
|
||||
project's designated container. Entering one resets the working directory — chain `cd` in the
|
||||
same command string.
|
||||
- Prefer the project's build script over hand-typed `dotnet` calls; it carries `-warnaserror`,
|
||||
the correct action ordering, and the asset completeness checks.
|
||||
- **Never stop, deploy to, or restart an application while the user has it running**, unless
|
||||
they have said to.
|
||||
|
||||
---
|
||||
|
||||
## 9. Related
|
||||
- [`../coding-dev.md`](../coding-dev.md) — the general rules this extends.
|
||||
- [`bash.md`](./bash.md) — for the release pipeline scripts around a .NET build.
|
||||
@@ -0,0 +1,157 @@
|
||||
---
|
||||
name: go
|
||||
description: >-
|
||||
Use this skill when writing, building, linting, testing, or releasing Go — including
|
||||
golangci-lint configuration, strict typing over map[string]interface{}, official SDK
|
||||
preference, CGO-free static builds, context handling, and the build gate.
|
||||
---
|
||||
|
||||
# Go — Rules & Preferences
|
||||
|
||||
Extends [`../coding-dev.md`](../coding-dev.md). Everything there applies; this adds Go specifics.
|
||||
|
||||
---
|
||||
|
||||
## 1. The Gate
|
||||
|
||||
```bash
|
||||
gofmt -l . # must print nothing
|
||||
go vet ./...
|
||||
golangci-lint run
|
||||
go test -race ./...
|
||||
go build ./...
|
||||
```
|
||||
|
||||
Wire this into a single entry point (`make check`, `scripts/build.sh`) so it cannot be
|
||||
partially run. **A skipped test fails the gate.** Add `govulncheck` for binary vulnerability
|
||||
scanning on anything that ships.
|
||||
|
||||
---
|
||||
|
||||
## 2. Linting — Strict Set
|
||||
|
||||
`golangci-lint` with a deliberately broad selection, not the defaults:
|
||||
|
||||
```yaml
|
||||
linters:
|
||||
enable:
|
||||
- staticcheck
|
||||
- errcheck # every returned error is handled
|
||||
- gosec # security findings
|
||||
- noctx # no HTTP request without a context
|
||||
- revive
|
||||
- misspell
|
||||
- unconvert
|
||||
- bodyclose # every response body is closed
|
||||
- goconst
|
||||
- ineffassign
|
||||
- nilerr
|
||||
```
|
||||
|
||||
`errcheck` and `bodyclose` catch the two most common real Go bugs. As always: fix rather than
|
||||
suppress, and when suppressing use a specific `//nolint:name // reason` with the reason.
|
||||
|
||||
---
|
||||
|
||||
## 3. Typing — Concrete, Not Dynamic
|
||||
|
||||
- **Strongly typed structs everywhere.** Avoid `map[string]interface{}` and reflection when a
|
||||
struct can be defined — including for JSON, config, and API payloads.
|
||||
- **Typed constants/enums**, not bare strings:
|
||||
```go
|
||||
type SyncStatus string
|
||||
|
||||
const (
|
||||
StatusSynced SyncStatus = "synced"
|
||||
StatusOutdated SyncStatus = "outdated"
|
||||
StatusDirty SyncStatus = "dirty"
|
||||
)
|
||||
```
|
||||
- **Concrete error types** with `errors.Is` / `errors.As`, not string comparison.
|
||||
- Keep types shared with a frontend structurally in sync with that frontend's types; when both
|
||||
exist, a change to one is incomplete without the other.
|
||||
|
||||
---
|
||||
|
||||
## 4. Errors
|
||||
|
||||
- **Every error is handled.** `errcheck` enforces it; do not `_ =` an error away without a
|
||||
comment explaining why it cannot matter.
|
||||
- Wrap with context: `fmt.Errorf("fetching %s: %w", name, err)`. Always `%w`, never `%v`, when
|
||||
the caller might need to inspect it.
|
||||
- Sentinel errors as package-level `var ErrNotFound = errors.New(...)`; typed errors when the
|
||||
caller needs data from them.
|
||||
- **`panic` only for genuinely unrecoverable programmer error**, never for expected runtime
|
||||
conditions. A library never panics on input it was designed to receive.
|
||||
- `defer` the cleanup immediately after acquiring the resource, always.
|
||||
|
||||
---
|
||||
|
||||
## 5. Context
|
||||
|
||||
- **Every function that does I/O takes `ctx context.Context` as its first parameter.**
|
||||
- Never store a context in a struct field.
|
||||
- Never pass `nil` — `context.TODO()` marks a genuine gap.
|
||||
- Honor cancellation: select on `ctx.Done()` in loops, and pass ctx down to every HTTP call
|
||||
(`noctx` enforces this).
|
||||
- Set timeouts on outbound requests. A default `http.Client` has no timeout at all.
|
||||
|
||||
---
|
||||
|
||||
## 6. Dependencies — Official SDKs First
|
||||
|
||||
Follow the global reuse-first ordering. In Go, strongly prefer **official/first-party SDKs**
|
||||
over third-party wrappers — they track API changes and handle auth and pagination correctly.
|
||||
|
||||
Choose **pure-Go implementations over CGO ones** whenever the trade is acceptable: a CGO
|
||||
dependency turns a static single-binary build into a toolchain and glibc problem, and rules
|
||||
out a `FROM scratch`/Alpine container image.
|
||||
|
||||
```bash
|
||||
CGO_ENABLED=0 go build -trimpath -ldflags="-s -w" -o bin/app ./cmd/app
|
||||
```
|
||||
|
||||
`go mod tidy` before committing, and commit `go.sum`.
|
||||
|
||||
---
|
||||
|
||||
## 7. Concurrency
|
||||
|
||||
- **Share memory by communicating.** Channels for handoff; `sync.Mutex` for guarding a struct's
|
||||
own fields. Don't mix both for the same state.
|
||||
- **`go test -race` is not optional** — it belongs in the gate, not in an occasional manual run.
|
||||
- Every goroutine has a defined exit path. `errgroup.Group` for a set of related goroutines so
|
||||
errors propagate and cancellation fans out.
|
||||
- **Events over polling** — subscribe to a watch/notify API rather than looping on a ticker.
|
||||
Where a ticker is genuinely necessary, make the interval configurable and document why.
|
||||
- Never leak a goroutine on a channel nobody reads.
|
||||
|
||||
---
|
||||
|
||||
## 8. Structure
|
||||
|
||||
- `cmd/<binary>/` for entry points; `pkg/` or `internal/` for the actual code.
|
||||
- `internal/` for anything that must not become public API — it is compiler-enforced.
|
||||
- One package per concern; **package names are lowercase, single-word, no underscores**, and
|
||||
never `util` or `common`.
|
||||
- Keep the exported surface small. Unexported by default.
|
||||
- Embed frontend/static assets with `//go:embed` for single-binary distribution.
|
||||
- File and function size limits from the general rules apply.
|
||||
|
||||
---
|
||||
|
||||
## 9. Testing
|
||||
|
||||
- Table-driven tests are the default idiom.
|
||||
- `t.Parallel()` where tests are genuinely independent.
|
||||
- `t.TempDir()` for filesystem work — it cleans itself up.
|
||||
- `httptest` for HTTP handlers and for faking upstreams; do not hit real services in unit tests.
|
||||
- **Regression test every fixed bug.**
|
||||
- **Never run destructive operations against real accounts or user data during validation** —
|
||||
temporary fixtures only.
|
||||
|
||||
---
|
||||
|
||||
## 10. Related
|
||||
- [`../coding-dev.md`](../coding-dev.md) — the general rules this extends.
|
||||
- [`js-typescript.md`](./js-typescript.md) — for the embedded frontend in a Go service.
|
||||
@@ -0,0 +1,202 @@
|
||||
---
|
||||
name: js-typescript
|
||||
description: >-
|
||||
Use this skill when writing, building, linting, testing, or releasing JavaScript or
|
||||
TypeScript — including Node, Bun, Deno, React, Next.js, and Astro projects. Covers the
|
||||
TypeScript-over-JSDoc-over-JS preference, strict compiler settings, banned constructs,
|
||||
React/hooks rules, resource lifecycle, and package/tooling choices.
|
||||
---
|
||||
|
||||
# TypeScript / JavaScript — Rules & Preferences
|
||||
|
||||
Extends [`../coding-dev.md`](../coding-dev.md). Everything there applies; this adds JS/TS specifics.
|
||||
|
||||
---
|
||||
|
||||
## 1. Language Choice — A Strict Preference Order
|
||||
|
||||
1. **TypeScript** — always the default for new code.
|
||||
2. **JavaScript with JSDoc type annotations** — acceptable when a project genuinely cannot
|
||||
adopt a build step, and `checkJs` is enabled so the annotations are actually enforced.
|
||||
3. **Plain untyped JavaScript** — last resort only.
|
||||
|
||||
Migrating an existing JS project to TS is worth proposing; do not do it unasked (scope rule).
|
||||
In a plain-JS codebase, **match it** — do not introduce a lone `.ts` file and a build step
|
||||
into a project that has neither.
|
||||
|
||||
---
|
||||
|
||||
## 2. Strict Compiler Settings
|
||||
|
||||
```jsonc
|
||||
{
|
||||
"compilerOptions": {
|
||||
"strict": true,
|
||||
"noUncheckedIndexedAccess": true,
|
||||
"noImplicitOverride": true,
|
||||
"noFallthroughCasesInSwitch": true,
|
||||
"noUnusedLocals": true,
|
||||
"noUnusedParameters": true,
|
||||
"exactOptionalPropertyTypes": true,
|
||||
"isolatedModules": true
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**`tsc --noEmit` must pass with 0 errors**, and it belongs in the build gate alongside lint
|
||||
and tests — not as a thing someone runs occasionally in their editor.
|
||||
|
||||
> [!NOTE]
|
||||
> Some established codebases deliberately relax `noImplicitAny` or `noUncheckedIndexedAccess`
|
||||
> because their idioms depend on it. Respect the project's `tsconfig.json`; the table above is
|
||||
> the default for **new** projects.
|
||||
|
||||
---
|
||||
|
||||
## 3. Banned Constructs
|
||||
|
||||
| Never | Use instead |
|
||||
| :--- | :--- |
|
||||
| `any` | `unknown` + narrowing, or a real generic |
|
||||
| `as unknown as T` | a type guard, or fix the source type |
|
||||
| `@ts-ignore` | `@ts-expect-error` with a one-line reason, only when unavoidable |
|
||||
| `!` non-null assertion | narrow with `if` or an early return |
|
||||
| `enum` / `const enum` | `as const` object + literal union |
|
||||
| `namespace` | ES modules |
|
||||
| Boxed primitives (`Number`, `String`, `Object`, `{}`, `Function`) | the primitive types |
|
||||
| `../../..` relative climbs | the configured path alias (`@/*`) |
|
||||
| `JSON.parse(JSON.stringify(x))` | `structuredClone` or `lodash.cloneDeep` |
|
||||
| `await new Promise(r => setTimeout(r, ms))` | a `sleep` helper from your utils |
|
||||
| `console.log` in shipped code | a real logger with levels |
|
||||
| Empty `catch {}` | handle it, or let it propagate |
|
||||
|
||||
- **`satisfies T` over `as T`** when the value already conforms. `as` is for genuine narrowing
|
||||
only — it is an assertion that silences the checker, not a conversion.
|
||||
- **Zero `any` in shared model types.** Frontend types that mirror a backend schema must stay
|
||||
structurally in sync with it and fully typed.
|
||||
|
||||
---
|
||||
|
||||
## 4. Use What Exists
|
||||
|
||||
**Search the codebase's own `utils/`, `common/`, and shared modules before writing anything.**
|
||||
Re-implementing an export that already exists is the single most common avoidable diff.
|
||||
|
||||
Never hand-roll: debounce/throttle (`lodash`), deep clone, clamp, date formatting
|
||||
(`date-fns` / `dayjs` / project standard), URL parsing, regex escaping, UUID generation,
|
||||
retry/backoff, or a semver comparator.
|
||||
|
||||
In a UI framework or client mod, **never recreate a component the host already provides** —
|
||||
a hand-rolled `<button>` loses theming, focus rings, and accessibility.
|
||||
|
||||
---
|
||||
|
||||
## 5. React
|
||||
|
||||
- **Conditional rendering returns `null`**, never `undefined` or `false`.
|
||||
- **List keys are stable identifiers.** Never `key={index}` on a mutable list.
|
||||
- **Don't mirror external state into `useState`.** Subscribe to the store with its own hook.
|
||||
- No `useMemo` / `useCallback` on cheap values that do not feed a dependency array. They are
|
||||
not free, and they obscure what is actually expensive.
|
||||
- **Hoist constant dependency arrays** to module scope (`const KEYS = [...] as const`). A fresh
|
||||
array literal in the render body re-subscribes on every render.
|
||||
- Prefer `<>…</>` fragments; `React.Fragment` only when the fragment needs a `key`.
|
||||
- Type props with a named `interface`, not `React.FC`.
|
||||
- Wrap anything injected into a host application's tree in an error boundary — an
|
||||
uncaught throw in injected code takes down the host's render, not just yours.
|
||||
- Components used as dynamic render targets must live at **module scope**. Defining a
|
||||
component inside another component remounts its whole subtree every render.
|
||||
|
||||
---
|
||||
|
||||
## 6. Resource Lifecycle — Everything Started Must Be Stopped
|
||||
|
||||
Every `setInterval`, long `setTimeout`, `addEventListener`, subscription, `ResizeObserver`,
|
||||
`IntersectionObserver`, `AbortController`, and `WebSocket` created in a setup path must be
|
||||
torn down in the matching teardown path — `stop()`, `useEffect` cleanup, or `finally`.
|
||||
|
||||
> [!CAUTION]
|
||||
> **`addEventListener` needs a named function reference.** An inline arrow passed to
|
||||
> `addEventListener` cannot be matched by `removeEventListener`, so the listener leaks
|
||||
> silently and accumulates across every mount.
|
||||
|
||||
```ts
|
||||
let intervalId: ReturnType<typeof setInterval> | undefined;
|
||||
|
||||
function start() { intervalId = setInterval(tick, 30_000); }
|
||||
function stop() { if (intervalId !== undefined) { clearInterval(intervalId); intervalId = undefined; } }
|
||||
```
|
||||
|
||||
Attach an `AbortController` to every long-lived `fetch` and abort it in cleanup.
|
||||
|
||||
---
|
||||
|
||||
## 7. Structure & Naming
|
||||
|
||||
- **Components**: PascalCase `.tsx`.
|
||||
- **Modules / utilities**: kebab-case `.ts`.
|
||||
- **Imports**: prefer the configured alias (`@/…`) over relative climbs.
|
||||
- Indentation and quote/semicolon style: **match the file you are editing**. Do not introduce
|
||||
a new formatter or lint config into a project that already has one.
|
||||
- **One file until it earns a split** — around 250 lines for a self-contained plugin/feature,
|
||||
or when a second file is genuinely reusable (`utils.ts`, `types.ts`, `components/`).
|
||||
Hard limits from the general rules still apply.
|
||||
|
||||
---
|
||||
|
||||
## 8. Async & Data
|
||||
|
||||
- `async`/`await` over raw `.then()` chains. No mixing both in one flow.
|
||||
- **Never leave a promise unawaited** unless you explicitly mean to, and mark it (`void p`)
|
||||
when you do.
|
||||
- `Promise.all` for independent work; sequential `await` only when there is a real dependency.
|
||||
- **Subscribe to events; never poll.** (Global rule — it applies with full force here.)
|
||||
- **Never store secrets in `localStorage` / `sessionStorage`.** Use the platform's real
|
||||
storage API, and namespace your keys.
|
||||
|
||||
---
|
||||
|
||||
## 9. Node / Runtime Boundaries
|
||||
|
||||
- In any sandboxed or privileged-split architecture (Electron, browser extensions, plugin
|
||||
hosts), the untrusted side must **never** import `fs`, `path`, `child_process`, `net`,
|
||||
`http`, or `electron` directly. Route through the designated IPC/native boundary.
|
||||
- Every IPC handler argument is **untrusted** — validate type, length, and content.
|
||||
- Filesystem paths from the other side: `normalize()` then assert `startsWith(<allowed root>)`
|
||||
before any read or write.
|
||||
- Subprocesses: `spawn` with an argv **array**. Never `exec` a constructed string, never
|
||||
`shell: true` with untrusted input.
|
||||
- Network: allowlist by origin, cap response size, cap redirect depth.
|
||||
- Errors crossing the boundary must be scrubbed — a raw `Error` leaks absolute paths.
|
||||
|
||||
---
|
||||
|
||||
## 10. Tooling & Tests
|
||||
|
||||
- Respect the project's runtime and package manager (`npm` / `pnpm` / `yarn` / `bun`) and its
|
||||
lockfile. Do not switch package managers or add a second lockfile.
|
||||
- Test runner: whatever the project uses (`vitest`, `bun test`, `jest`). Tests live beside the
|
||||
code as `*.test.ts(x)` unless the project says otherwise.
|
||||
- **Add unit tests for new logic and route tests for new handlers.** Prioritize coverage on
|
||||
auth, persistence, and anything that talks to a third party.
|
||||
- Lint with the project's config (`eslint.config.mjs` and friends). **Do not add a new lint or
|
||||
format config** to a repo that already has one.
|
||||
- **Know the project's expected test baseline.** Some inherited suites are not all-green on a
|
||||
clean checkout; judge regressions against the documented baseline rather than a raw run —
|
||||
and if a baseline file exists, use it.
|
||||
|
||||
---
|
||||
|
||||
## 11. Framework Versions Move Fast
|
||||
|
||||
> [!WARNING]
|
||||
> Next.js, Astro, React, and the major bundlers ship breaking changes regularly, and their
|
||||
> current APIs frequently differ from what is in a model's training data. **Read the version's
|
||||
> own docs in `node_modules/<pkg>/dist/docs/` or the project's pinned documentation before
|
||||
> writing code against them.** Heed deprecation notices rather than pattern-matching from memory.
|
||||
|
||||
---
|
||||
|
||||
## 12. Related
|
||||
- [`../coding-dev.md`](../coding-dev.md) — the general rules this extends.
|
||||
- [`bash.md`](./bash.md) — for the build/release scripts around these projects.
|
||||
@@ -0,0 +1,153 @@
|
||||
---
|
||||
name: python
|
||||
description: >-
|
||||
Use this skill when writing, linting, type-checking, testing, or packaging Python —
|
||||
including async code, CLI tools, bot cogs, and library packages. Covers strict typing with
|
||||
mypy, ruff configuration, virtualenv discipline, async patterns, and packaging.
|
||||
---
|
||||
|
||||
# Python — Rules & Preferences
|
||||
|
||||
Extends [`../coding-dev.md`](../coding-dev.md). Everything there applies; this adds Python specifics.
|
||||
|
||||
---
|
||||
|
||||
## 1. The Gate
|
||||
|
||||
```bash
|
||||
ruff format --check .
|
||||
ruff check .
|
||||
mypy --strict .
|
||||
pytest
|
||||
```
|
||||
|
||||
All four clean before anything is called done. Configure them in `pyproject.toml` so the
|
||||
editor, the CLI, and CI all read the same settings.
|
||||
|
||||
---
|
||||
|
||||
## 2. Typing — Strict
|
||||
|
||||
**Every function gets annotated**, including `-> None`. Type hints are not optional
|
||||
documentation; they are the checker's input.
|
||||
|
||||
```toml
|
||||
[tool.mypy]
|
||||
strict = true
|
||||
warn_unreachable = true
|
||||
warn_return_any = true
|
||||
disallow_untyped_defs = true
|
||||
```
|
||||
|
||||
- **Never bare `Any`.** Use a `Protocol`, a `TypeVar`, or `object` + narrowing.
|
||||
- `X | None` over `Optional[X]`; `list[str]` over `List[str]` (modern syntax, no `typing` import).
|
||||
- `TypedDict` or a dataclass for structured dicts — not `dict[str, Any]`.
|
||||
- `Literal` and `Enum` for closed sets of values, not bare strings.
|
||||
- `@dataclass(frozen=True, slots=True)` for value objects.
|
||||
- Third-party library missing stubs: install `types-*` if it exists, otherwise a narrowly
|
||||
scoped `# type: ignore[import-untyped]` with a comment — never a blanket module-level ignore.
|
||||
|
||||
---
|
||||
|
||||
## 3. Linting
|
||||
|
||||
`ruff` is the linter and formatter (it replaces flake8, isort, black, pyupgrade, and most
|
||||
plugins). Enable a broad rule set rather than the default minimum:
|
||||
|
||||
```toml
|
||||
[tool.ruff.lint]
|
||||
select = ["E", "F", "W", "I", "N", "UP", "B", "A", "C4", "SIM", "RUF", "ASYNC", "S", "PTH"]
|
||||
```
|
||||
|
||||
`S` (bandit security rules) and `ASYNC` are worth the noise. As always: fix, don't suppress —
|
||||
and when you must suppress, use a specific code (`# noqa: S603`) with a reason.
|
||||
|
||||
---
|
||||
|
||||
## 4. Environments
|
||||
|
||||
- **Always a virtualenv or project-managed environment** (`uv`, `poetry`, `pdm`, `venv`).
|
||||
Never install into the system interpreter, and never `pip install --user` as a workaround
|
||||
for an immutable OS — use a container or a venv.
|
||||
- `uv` is the preferred installer/resolver where free choice exists; it is dramatically faster
|
||||
and lockfile-native.
|
||||
- Commit the lockfile. Pin the Python version in `pyproject.toml` (`requires-python`).
|
||||
- `pathlib.Path` over `os.path` everywhere (ruff's `PTH` rules enforce this).
|
||||
|
||||
---
|
||||
|
||||
## 5. Errors & Logging
|
||||
|
||||
- **Specific exceptions only.** `except Exception:` needs a reason; bare `except:` is never
|
||||
acceptable (it catches `KeyboardInterrupt` and `SystemExit`).
|
||||
- **Never swallow silently.** If you catch and continue, log at `warning` or above.
|
||||
- `raise ... from err` to preserve the chain.
|
||||
- Custom exception types deriving from a single package-level base, so callers can catch the
|
||||
whole family.
|
||||
- **`logging` module, never `print`,** in anything that isn't a CLI writing to stdout as its
|
||||
actual output. One `logger = logging.getLogger(__name__)` per module, at module scope.
|
||||
- **Never log secrets** — tokens, auth headers, message content, personal data.
|
||||
|
||||
---
|
||||
|
||||
## 6. Async
|
||||
|
||||
- `asyncio` with `async`/`await`. **Never block the event loop** — no `time.sleep`, no
|
||||
synchronous `requests`, no blocking file I/O in a coroutine. Use `asyncio.to_thread` for
|
||||
genuinely blocking calls.
|
||||
- `httpx` (or the framework's own client) over `requests` in async code.
|
||||
- **`asyncio.TaskGroup`** (3.11+) over bare `create_task` — it propagates exceptions and
|
||||
cancels siblings instead of losing them to an unawaited task.
|
||||
- **Every `create_task` result must be held in a reference**, or the garbage collector can
|
||||
cancel it mid-flight.
|
||||
- Cancellation is cooperative: clean up in `finally`, and never swallow `CancelledError`.
|
||||
- **Events over polling.** Subscribe to the library's event/callback API; do not loop on a
|
||||
timer. Where polling is genuinely unavoidable (no event source exists), use a **staggered
|
||||
backoff** rather than a fixed interval, and say why polling was necessary.
|
||||
|
||||
---
|
||||
|
||||
## 7. Rate Limiting & External Services
|
||||
|
||||
When talking to a rate-limited API (a chat platform, a store, a tracker):
|
||||
|
||||
- **Funnel outbound calls through a single queue/worker** rather than calling from arbitrary
|
||||
call sites. It is the only place a limit can actually be enforced.
|
||||
- **Backoff with jitter** on retry; never a tight retry loop.
|
||||
- Respect `Retry-After` and documented limits; assume undocumented ones exist.
|
||||
- **Be extremely careful scraping real consumer services.** Conservative delays, realistic
|
||||
headers, plenty of failsafes, and abort fast when a response looks unexpected. Assume you
|
||||
are one mistake away from a ban.
|
||||
|
||||
---
|
||||
|
||||
## 8. Structure
|
||||
|
||||
- Package layout: `src/<package>/`, tests in `tests/`.
|
||||
- **Shared behavior goes in a real shared module**, imported by each consumer — not
|
||||
copy-pasted between sibling packages. When three components grow the same queue/retry/
|
||||
formatting logic, that is the signal to extract it.
|
||||
- Reusable, generic functionality (a format parser, a protocol client) becomes **its own
|
||||
installable package** with its own repo and version, consumed as a dependency.
|
||||
- Keep persistent state in the framework's own config/storage system so it survives restarts;
|
||||
do not invent a parallel JSON file beside it.
|
||||
- File and function size limits from the general rules apply.
|
||||
|
||||
---
|
||||
|
||||
## 9. Testing
|
||||
|
||||
- `pytest`, with `pytest-asyncio` for coroutines.
|
||||
- Fixtures over setup/teardown methods; `tmp_path` for anything touching the filesystem.
|
||||
- **Regression test every fixed bug.**
|
||||
- Mock at the network boundary (`respx`, `responses`), not by monkeypatching your own
|
||||
internals — a test that patches the code under test proves nothing.
|
||||
- **Never exercise destructive operations against real accounts or real data.** Temporary
|
||||
fixtures only.
|
||||
- `pytest -p no:randomly` only when order genuinely matters, and note why.
|
||||
|
||||
---
|
||||
|
||||
## 10. Related
|
||||
- [`../coding-dev.md`](../coding-dev.md) — the general rules this extends.
|
||||
- [`bash.md`](./bash.md) — for the surrounding build and deploy scripts.
|
||||
@@ -0,0 +1,188 @@
|
||||
---
|
||||
name: rust
|
||||
description: >-
|
||||
Use this skill when writing, building, linting, testing, or releasing Rust code — including
|
||||
workspace lint configuration, clippy/fmt gates, error handling with Result/thiserror,
|
||||
unsafe policy, async patterns, and cargo workspace/submodule layout.
|
||||
---
|
||||
|
||||
# Rust — Rules & Preferences
|
||||
|
||||
Extends [`../coding-dev.md`](../coding-dev.md). Everything there applies; this adds Rust specifics.
|
||||
|
||||
---
|
||||
|
||||
## 1. The Gate
|
||||
|
||||
Nothing is "done" until all of these are clean:
|
||||
|
||||
```bash
|
||||
cargo fmt --all --check
|
||||
cargo clippy --workspace --all-targets --all-features
|
||||
cargo test --workspace
|
||||
cargo doc --workspace --no-deps
|
||||
cargo build --release
|
||||
```
|
||||
|
||||
> [!IMPORTANT]
|
||||
> **`--workspace` is not optional.** Without it only the root package is checked and every
|
||||
> member crate's warnings stay invisible. This has hidden real warnings for weeks at a time.
|
||||
> `--all-targets` additionally covers tests, benches, and examples — which are also code.
|
||||
|
||||
- `cargo fmt` before every commit. **No hand-formatting**, ever.
|
||||
- `cargo doc` matters: a broken intra-doc link is a reference to something that no longer
|
||||
exists, which is worth knowing about.
|
||||
- Run the project's build script (`./scripts/build.sh`) if it has one — it wires these
|
||||
together plus size checks and a smoke run.
|
||||
|
||||
---
|
||||
|
||||
## 2. Lints — Pedantic On, Configured In One Place
|
||||
|
||||
```toml
|
||||
# Cargo.toml (workspace root)
|
||||
[workspace.lints.clippy]
|
||||
pedantic = { level = "warn", priority = -1 }
|
||||
too_many_lines = "warn"
|
||||
unwrap_used = "warn"
|
||||
|
||||
[workspace.lints.rust]
|
||||
unsafe_code = "forbid"
|
||||
```
|
||||
|
||||
```toml
|
||||
# every member crate
|
||||
[lints]
|
||||
workspace = true
|
||||
```
|
||||
|
||||
> [!CAUTION]
|
||||
> **Lint config lives in `[workspace.lints]` only.** A package that repeats the configuration
|
||||
> carries a second copy that drifts — which is how a binary once kept reading its own stale
|
||||
> allows while the workspace's were being actively edited.
|
||||
|
||||
- **Never `#[allow]` on a whim.** If a lint is genuinely wrong for the codebase, allow it
|
||||
**workspace-wide** with a comment explaining why, so the decision is visible.
|
||||
- **Re-test every `#[allow]` periodically.** If removing one produces no warning, delete it.
|
||||
- `too_many_lines` is the mechanical enforcement of the 100-line function limit. A function
|
||||
that trips it wants extracting, not an allow.
|
||||
|
||||
---
|
||||
|
||||
## 3. Errors & Panics
|
||||
|
||||
- **`Result` and `Option` everywhere.** `thiserror` for library error enums;
|
||||
`anyhow` is acceptable at the application/binary boundary only.
|
||||
- **No `unwrap()` or `expect()` outside tests and `main`.** Anything that can be absent at
|
||||
runtime — a device, a file, a network peer, an env var — must be handled. Hardware and
|
||||
network resources appear and disappear while the program runs.
|
||||
- No `panic!` as flow control. A library never panics on input it was designed to receive.
|
||||
- Never `?`-swallow context — attach it (`.context(...)` / a typed variant) so the error says
|
||||
where it came from.
|
||||
|
||||
---
|
||||
|
||||
## 4. `unsafe`
|
||||
|
||||
**Forbidden by default**, enforced in `Cargo.toml` with `unsafe_code = "forbid"`.
|
||||
|
||||
If an FFI binding genuinely requires it, it goes behind a **safe wrapper in exactly one
|
||||
module**, with a `// SAFETY:` comment on every block stating the invariant being upheld.
|
||||
`unsafe` scattered through call sites is not acceptable.
|
||||
|
||||
---
|
||||
|
||||
## 5. Dependencies & Workspace Layout
|
||||
|
||||
Follow the global ordering (reuse → fork → write). In Rust specifically:
|
||||
|
||||
- Search crates.io and check maintenance status before adding. Prefer pure-Rust crates over
|
||||
ones requiring a C toolchain when the difference is not material — a C dependency turns a
|
||||
one-command build into a container requirement.
|
||||
- **Pin precisely when it matters.** If you need an API that only exists on a git revision,
|
||||
pin the revision and **write down why** — a future reader will otherwise "helpfully"
|
||||
bump it to the crates.io release that lacks the API.
|
||||
- **Reusable logic goes in its own crate**, published separately, with the application as a
|
||||
consumer. The workspace layout that follows from this:
|
||||
```
|
||||
crates/<name>-core/ # all reusable logic, no UI, no framework deps
|
||||
crates/<name>-proto/ # wire types & protocol parsing, dependency-light
|
||||
src/ # or crates/<name>-ui — presentation only
|
||||
```
|
||||
- **Submodule hygiene**: commit and push inside the submodule crate first, then commit the
|
||||
updated SHA pointer in the parent. Match each repo's own commit-trailer and identity
|
||||
conventions — a public library repo and a private app repo often differ deliberately.
|
||||
|
||||
---
|
||||
|
||||
## 6. Async
|
||||
|
||||
- Tokio runtime with `futures` streams; `async_trait` where trait methods must be async.
|
||||
- **Model new flows as streams or async methods**, matching what the codebase already does.
|
||||
- **Never block in async context.** Use `spawn_blocking` for genuinely blocking work.
|
||||
- Subscribe to event streams; never poll on a timer (see the global events-over-polling rule).
|
||||
- Don't short-circuit a hand-written `Stream` impl that manually pumps backends — it usually
|
||||
encodes ordering guarantees that are not obvious from the signature.
|
||||
|
||||
---
|
||||
|
||||
## 7. Feature Flags & `cfg`
|
||||
|
||||
- Feature flags declared in the root `Cargo.toml`.
|
||||
- **Gate at module level, not per function** — per-function `cfg` leaves a trail of empty
|
||||
stubs and makes the real platform differences hard to see.
|
||||
- Adding a platform backend: declare the feature, create the gated module, and **log which
|
||||
backend was selected at startup**. Silent backend selection is very hard to debug remotely.
|
||||
- Use `build.rs`-exported configs for conditions that aren't plain features.
|
||||
|
||||
---
|
||||
|
||||
## 8. Style Details
|
||||
|
||||
- `unsafe`-free, `unwrap`-free, and formatted — see above.
|
||||
- **No `pub` on anything that doesn't need to cross a module boundary.** Default to private
|
||||
and widen deliberately.
|
||||
- Max ~5 parameters; past that, pass a struct.
|
||||
- Prefer `f32` for UI/geometry when the framework's native unit is `f32` — mixing in `f64`
|
||||
produces a stream of casts and rounding inconsistencies.
|
||||
- Derive rather than hand-implement (`Debug`, `Clone`, `Default`, `PartialEq`) unless the
|
||||
hand implementation is doing something a derive cannot.
|
||||
- `#[non_exhaustive]` on public enums/structs that are likely to grow.
|
||||
|
||||
---
|
||||
|
||||
## 9. Testing
|
||||
|
||||
- Unit tests inline in `#[cfg(test)] mod tests`; integration tests in `tests/`.
|
||||
- `cargo test --workspace` — plus `--release` when timing or optimization matters to the
|
||||
behavior under test.
|
||||
- **Regression test every fixed bug.**
|
||||
- A dummy/mock backend that exercises the full pipeline without real hardware is worth
|
||||
building early — it is the only way most device code gets tested at all.
|
||||
- Never point test output at real hardware. Route test signal to a virtual/null endpoint and
|
||||
**verify the route resolved** — most tools silently fall back to the system default when
|
||||
the requested target does not exist, which sends your test straight at the user.
|
||||
|
||||
---
|
||||
|
||||
## 10. Building in Containers
|
||||
|
||||
When the crate needs system headers the host does not have (audio, graphics, webkit),
|
||||
build inside the project's designated container. Chain `cd` inside the same command string —
|
||||
entering a container resets the working directory:
|
||||
|
||||
```bash
|
||||
distrobox enter <container> -- bash -c "cd /path/to/project && cargo build --release"
|
||||
```
|
||||
|
||||
Prefer the project's `scripts/build.sh` over a hand-typed invocation; it also handles job
|
||||
throttling so a release build does not saturate the machine.
|
||||
|
||||
**Split so that as little as possible needs the container**: a `-core` crate with no GUI
|
||||
dependencies builds and tests directly on the host, which is seconds instead of minutes.
|
||||
|
||||
---
|
||||
|
||||
## 11. Related
|
||||
- [`../coding-dev.md`](../coding-dev.md) — the general rules this extends.
|
||||
- [`c-cpp.md`](./c-cpp.md) — when bindgen/FFI crosses into a C library.
|
||||
+293
@@ -0,0 +1,293 @@
|
||||
---
|
||||
name: coding-dev
|
||||
description: >-
|
||||
Use this skill whenever writing, reviewing, refactoring, building, testing, or releasing code
|
||||
in any language. Defines standing preferences on strictness, dependency choice, file and function
|
||||
size limits, test discipline, build output handling, error/warning policy, and commit hygiene.
|
||||
Links to per-language rules under code-languages/ for Rust, TypeScript/JavaScript, Bash, Python,
|
||||
Go, C#/.NET, and C/C++.
|
||||
---
|
||||
|
||||
# Coding & Development — Standing Rules and Preferences
|
||||
|
||||
These are the defaults for **all** code work, in any language. They are preferences with
|
||||
reasons attached, not style trivia — most exist because ignoring them caused a real problem.
|
||||
|
||||
> [!IMPORTANT]
|
||||
> **A project's own rules win.** If a repository has an `AGENTS.md`, `CLAUDE.md`, `AGENT.md`,
|
||||
> `.rules`, or `CONTRIBUTING.md`, read it first — it is more specific than this document and
|
||||
> overrides it on conflict. This file is the default for everything those files do not say.
|
||||
|
||||
Per-language specifics live in [`code-languages/`](./code-languages/):
|
||||
|
||||
| Language | Rules |
|
||||
| :--- | :--- |
|
||||
| Rust | [`code-languages/rust.md`](./code-languages/rust.md) |
|
||||
| TypeScript / JavaScript | [`code-languages/js-typescript.md`](./code-languages/js-typescript.md) |
|
||||
| Bash / Shell | [`code-languages/bash.md`](./code-languages/bash.md) |
|
||||
| Python | [`code-languages/python.md`](./code-languages/python.md) |
|
||||
| Go | [`code-languages/go.md`](./code-languages/go.md) |
|
||||
| C# / .NET | [`code-languages/csharp-dotnet.md`](./code-languages/csharp-dotnet.md) |
|
||||
| C / C++ | [`code-languages/c-cpp.md`](./code-languages/c-cpp.md) |
|
||||
|
||||
---
|
||||
|
||||
## 1. Strictness — Maximum, Always
|
||||
|
||||
**Configure every linter, compiler, and type checker as strictly as the toolchain allows.**
|
||||
Strict mode is the starting point, not an aspiration to migrate toward later.
|
||||
|
||||
- Warnings are errors in CI and in the build gate (`-warnaserror`, `-D warnings`, `--strict`).
|
||||
- Enable the pedantic/extra lint tiers, not just the defaults.
|
||||
- Type checking must pass with **zero** errors — `tsc --noEmit`, `mypy`, `cargo check` alike.
|
||||
- Never weaken a check to make a build pass. Fix the failing step. If a check is genuinely
|
||||
wrong for the codebase, disable it **project-wide in one place with a comment explaining
|
||||
why**, so the decision is visible and reviewable — never with a scattered inline suppression.
|
||||
|
||||
### Suppressions are a last resort, and they expire
|
||||
|
||||
- Try hard to actually fix an error or warning before suppressing it.
|
||||
- When you do suppress one, **say so explicitly in your report to the user** — name the
|
||||
warning, where it is, and why it could not be fixed. A silent suppression is the failure
|
||||
mode this rule exists to prevent.
|
||||
- **Re-test suppressions periodically.** Removing an `#[allow]` / `// eslint-disable` /
|
||||
`#pragma warning disable` that no longer suppresses anything should produce no warning —
|
||||
if it doesn't, delete it. Stale suppressions accumulate and hide real regressions.
|
||||
|
||||
---
|
||||
|
||||
## 2. Never Hide Build, Test, or Lint Output
|
||||
|
||||
**Do not pipe build, compile, lint, format, or test output through `grep`, `tail`, `head`,
|
||||
`sed`, or any other filter.** Run the command so its complete output is visible.
|
||||
|
||||
**Why:** filtering hides warnings, notes, and diagnostics that did not match the pattern.
|
||||
Grepping for `^warning|^error` drops multi-line notes, help text, deprecation notices, and
|
||||
anything a tool emits in an unexpected format.
|
||||
|
||||
```bash
|
||||
# WRONG — silently drops notes, helps, and deprecations
|
||||
cargo clippy 2>&1 | grep -E "^(warning|error)"
|
||||
|
||||
# RIGHT
|
||||
cargo clippy --workspace --all-targets --all-features
|
||||
```
|
||||
|
||||
If output is genuinely too large, **narrow the command** (one test, one package, one target)
|
||||
rather than filtering its output. The same applies to logging: do not swallow stderr, do not
|
||||
redirect diagnostics to `/dev/null`, and do not set a log level that hides warnings during a
|
||||
verification run.
|
||||
|
||||
---
|
||||
|
||||
## 3. Dependencies — Reuse Before You Build
|
||||
|
||||
A strict ordering for obtaining any non-trivial functionality:
|
||||
|
||||
1. **Use an existing library / crate / package / official SDK** that already does it.
|
||||
2. **If one is close but not exactly right, fork it** (as a git submodule or vendored fork)
|
||||
and modify it.
|
||||
3. **Write your own implementation only when nothing else fits** — and say why, explicitly.
|
||||
|
||||
**Why:** the ecosystem has already solved correctness, edge cases, and platform quirks that
|
||||
a fresh implementation will rediscover slowly and incompletely.
|
||||
|
||||
Before hand-rolling any subsystem — a protocol client, a parser, a date formatter, a
|
||||
debounce, a retry/backoff, a semver comparator — **search first and state the finding.**
|
||||
Prefer official/first-party SDKs over third-party wrappers.
|
||||
|
||||
### The corollary: new generic code becomes its own package
|
||||
|
||||
**When you implement something generic that no existing package provided — a parser or
|
||||
reader for a file format, a protocol implementation, a client for an undocumented API —
|
||||
it becomes its own package/crate/module in its own repository**, which the application then
|
||||
depends on like any other dependency.
|
||||
|
||||
**Why:** it keeps the app's tree focused on the app, it forces a clean public API boundary,
|
||||
and it gives back the library that was missing in the first place. Structure the split so
|
||||
the reusable core has no UI, no framework, and no app-specific types — only the app shell
|
||||
depends on those.
|
||||
|
||||
> [!TIP]
|
||||
> Design for this from the start: put **all reusable logic in a core library** and keep the
|
||||
> UI/CLI layer as presentation only. A core without GUI dependencies also builds and tests
|
||||
> far faster, often without the app's heavyweight toolchain.
|
||||
|
||||
---
|
||||
|
||||
## 4. Size Limits — Files and Functions
|
||||
|
||||
| Unit | Soft target | Split at | Hard limit |
|
||||
| :--- | :--- | :--- | :--- |
|
||||
| **Source file** | ~400 lines | 600 lines | **1000 lines** |
|
||||
| **Function** | under 50 lines | — | **100 lines** |
|
||||
| **Function parameters** | 3–4 | — | ~5, then pass a struct/object |
|
||||
| **Nesting depth** | 2 | — | 3, then extract |
|
||||
|
||||
- **Enforce the function limit with the linter, not by eye** (e.g. Clippy's `too_many_lines`).
|
||||
A function that trips it wants extracting, not a suppression.
|
||||
- **Enforce the file limit in the build script** — a check that fails over the hard limit and
|
||||
*names* anything past the soft split point, so the seam gets found while splitting is cheap.
|
||||
- **Split by concern, never by line count.** A large `strip.rs` becomes
|
||||
`strip/fader.rs`, `strip/knobs.rs`, `strip/routing.rs` — never `strip1.rs` / `strip2.rs`.
|
||||
- One coherent responsibility per module. A module that draws widgets should not also own
|
||||
application state.
|
||||
|
||||
---
|
||||
|
||||
## 5. Tests
|
||||
|
||||
- **Write tests for every feature where testing is possible.** State plainly when something
|
||||
is untestable (GUI, hardware, live third-party service) rather than quietly skipping it.
|
||||
- **Every bug that was fixed gets a regression test.** A bug that broke once will break again;
|
||||
the test is what makes the second time cheap. This is the highest-value test you can write.
|
||||
- **A skipped test fails the gate.** Silently skipped tests are worse than missing ones —
|
||||
they report green.
|
||||
- Unit tests for logic; integration tests for protocol/boundary behavior.
|
||||
- **Never test destructive operations against real data.** Use fixtures, temporary
|
||||
directories, injected backends, and disposable test accounts. The user's real config,
|
||||
data, devices, accounts, and files must never be used as scratch space.
|
||||
- **Prove the test exercises the path under test.** A tool that silently falls back to a
|
||||
default target when the requested one does not resolve will produce a passing measurement
|
||||
of the wrong thing. Verify the wiring before trusting the result.
|
||||
- **Test the value, not the presence of the key.** A check that counts entries which exist
|
||||
will pass against a cleared or null value — and reads exactly like a working fix.
|
||||
|
||||
---
|
||||
|
||||
## 6. Verification — Before Claiming Anything Works
|
||||
|
||||
Run the **whole** gate, not the convenient part of it. A typical full gate:
|
||||
|
||||
> format check → lint (strict/pedantic) → type check → build → tests (with race/sanitizer
|
||||
> where available) → docs build → size limits → smoke run
|
||||
|
||||
- **Prefer the project's build script** (`./scripts/build.sh`, `make check`, `./build.sh --lint`)
|
||||
over hand-typed commands. It encodes steps you will otherwise forget, and it stays correct
|
||||
when the toolchain moves.
|
||||
- **Read the numbers, not just the verdict.** A suppression count that has grown is worth
|
||||
noticing even when everything passes.
|
||||
- **Confirm the binary you are testing contains the change.** A file existing proves a file
|
||||
exists, not that it is current. Compare its mtime against the commit, or wait for the build
|
||||
to actually report success — testing a stale binary reads exactly like "the fix didn't work".
|
||||
- **A change to visual/UI code is not done until it has been looked at.** Build, run,
|
||||
screenshot, compare.
|
||||
- **State plainly what is stubbed.** A component that draws its frame but has no behavior is a
|
||||
scaffold, not a finished component — say so rather than implying completion.
|
||||
|
||||
---
|
||||
|
||||
## 7. Architecture Preferences
|
||||
|
||||
- **Events over polling — always.** When there is an event, callback, channel, or watch API to
|
||||
subscribe to, use it. Do **not** settle for a polling loop because a benchmark shows it
|
||||
currently costs nothing; a measurement of 0% CPU does not make polling the right design. It
|
||||
adds latency and can miss or coalesce events. If existing code polls where an event exists,
|
||||
treat that as a finding worth fixing. Only poll when no event source exists — and say so.
|
||||
- **Don't over-guard.** Check only conditions that can actually occur. A null check on a
|
||||
non-optional value, a `try/catch` around code that cannot throw, or an optional-chain on a
|
||||
type-guaranteed value is dead defensive code, not safety.
|
||||
- **No abstraction for one or two call sites.** A factory used once is just a function call.
|
||||
No class wrapping a single function, no state machine for a boolean, no
|
||||
`Manager`/`Handler`/`Strategy`/`Provider` suffix unless multiple implementations exist.
|
||||
- **Less code with the same behavior wins.** Between equivalent solutions, the shorter ships.
|
||||
Three similar lines beat a premature helper.
|
||||
- **Delete dead code, don't comment it out.** That is what version control is for.
|
||||
- **Don't cache what a store already owns.** Read from the source of truth on demand; cache
|
||||
only what has no source of truth.
|
||||
- **A search-and-replace that matches nothing is a silent failure.** Assert the target string
|
||||
exists before replacing, and verify the result afterward.
|
||||
|
||||
---
|
||||
|
||||
## 8. Scope Discipline
|
||||
|
||||
- **Solve the problem at hand.** No refactors unless asked. No "while I was in there" cleanups.
|
||||
- **Smallest diff that correctly solves it.**
|
||||
- **Don't refactor code you weren't asked to touch**, and don't mix unrelated concerns in one
|
||||
change — backend work and UI work land separately.
|
||||
- When you notice adjacent work worth doing, **describe it** rather than absorbing it.
|
||||
- **Check `git status --short` before editing** and preserve unrelated in-progress changes.
|
||||
- **Verify a TODO before acting on it.** Task documents are leads, not facts — grep for the
|
||||
symbol, read the function, check the history. Work has been redone from scratch because a
|
||||
stale TODO claimed something was missing that had shipped hours earlier.
|
||||
|
||||
---
|
||||
|
||||
## 9. Comments & Naming
|
||||
|
||||
- **Comment the *why*, never the *what*.** "A gap here, matching the reference layout" is
|
||||
useful; `// draw the button` is not.
|
||||
- **Don't narrate changes in comments** ("changed this to fix X") — that is git's job.
|
||||
- Keep existing comments; they carry context you do not have.
|
||||
- **Natural human text in user-facing strings** — errors, descriptions, toasts. Sentence case,
|
||||
ending in a period, no robotic phrasing.
|
||||
- **Never hardcode** what a constant, config file, or generated table already defines —
|
||||
endpoints, colors, class names, translated strings, magic identifiers.
|
||||
- Names checked mechanically stay correct; names checked by memory drift. If a project has a
|
||||
naming rule that matters (a one-letter difference between the app and its library, say),
|
||||
**put it in the build gate**.
|
||||
|
||||
---
|
||||
|
||||
## 10. Errors, Logging & Security
|
||||
|
||||
- Use the language's structured error type; do not stringify errors as the primary mechanism.
|
||||
- **Never swallow an error silently.** No empty catch blocks.
|
||||
- Use a real logger with levels — `debug` for traces, `info` for lifecycle, `warn` for
|
||||
recoverable, `error` for unrecoverable. Not bare `print`/`console.log`.
|
||||
- **Never log secrets** — tokens, auth headers, passwords, message content, personal data.
|
||||
- **Never commit secrets.** Reference an environment file or secret store; commit only an
|
||||
`.env.example` with empty values.
|
||||
- **Treat every input from outside the trust boundary as hostile** — validate type, length,
|
||||
and content. Normalize and bounds-check any path before touching the filesystem with it.
|
||||
Never pass an externally-derived string to a shell.
|
||||
- **Be extremely careful automating against real third-party services.** Use conservative
|
||||
rate limits, generous delays, retries with backoff, and abort fast when a response looks
|
||||
wrong. Assume you are one mistake away from a ban or a real-world side effect.
|
||||
|
||||
---
|
||||
|
||||
## 11. Git & Commits
|
||||
|
||||
- **Conventional Commits**: `feat(scope): …`, `fix(translator): …`, `test: …`, `docs: …`.
|
||||
- Short, imperative subject lines.
|
||||
- **Commit incrementally as work lands.** Never leave a large batch of uncommitted work at
|
||||
the end of a task.
|
||||
- **Submodules**: commit and push the submodule first, then the updated pointer in the parent.
|
||||
Never leave a submodule commit unpushed — the parent would reference a commit nobody can fetch.
|
||||
- Match the repository's existing trailer and attribution conventions; some repositories
|
||||
deliberately carry none.
|
||||
|
||||
---
|
||||
|
||||
## 12. Reporting Work Honestly
|
||||
|
||||
- If tests fail, **say so and show the output**. If a step was skipped, say that.
|
||||
- If a warning was suppressed rather than fixed, **name it**.
|
||||
- Distinguish verified from unverified: GUI behavior, packaging, hardware, and live
|
||||
third-party interactions are usually unverified unless you actually exercised them.
|
||||
- Do not claim a visual match without having compared the two images.
|
||||
- **Prefer the boring explanation.** A typo, a stale binary, or a self-matching pattern is
|
||||
far more likely than a toolchain or sandbox bug — and an environment explanation is more
|
||||
flattering and arrives faster, which is exactly why it is the one to distrust.
|
||||
|
||||
---
|
||||
|
||||
## 13. Environment & Tooling
|
||||
|
||||
- **Read `<tool> --help` before using a CLI.** Do not guess flags, and do not write an ad-hoc
|
||||
script when an existing tool already does the job.
|
||||
- **Build inside the project's designated environment** (container, venv, toolchain manager)
|
||||
rather than the host, when the project specifies one. Note that entering a container
|
||||
typically resets the working directory — chain `cd` inside the same command string.
|
||||
- **Don't saturate the machine.** A full release build that consumes every core makes the
|
||||
workstation unusable. When something latency-sensitive is running, halve the job count and
|
||||
`nice` the build.
|
||||
- **Prefer long-running work in the background** over blocking wait loops. Never write
|
||||
`until <check>; do sleep 2; done` — it hangs the terminal and has to be interrupted by hand.
|
||||
|
||||
---
|
||||
|
||||
## 14. Related Skills
|
||||
- [`code-languages/`](./code-languages/) — per-language rules that extend and specialize this document.
|
||||
Reference in new issue
Block a user