Skip to content

Commit c17d9f9

Browse files
authored
Introduce CLAUDE.md (#1375)
### What does this PR do? We've found the claude CLI tool is pretty helpful in this project, see #1372 for one example. This file is introduced to follow the recommendations in https://www.anthropic.com/engineering/claude-code-best-practices. ### Motivation Tooling improvements.
1 parent 3c2c850 commit c17d9f9

File tree

1 file changed

+73
-0
lines changed

1 file changed

+73
-0
lines changed

CLAUDE.md

Lines changed: 73 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,73 @@
1+
# Design Goals
2+
3+
Lading is a performance tool. It's behavior has consequences on the development
4+
practices of large number of engineers and so lading must be:
5+
6+
* strictly 'faster' than targets, users must not wonder if their target has hit
7+
a bottleneck or lading has,
8+
* deterministic, targets must receive the same load across all instances of
9+
lading else replication of results is impossible and
10+
* extensible, lading must be available and capable of being extended for a
11+
variety of use-cases.
12+
13+
No change is valid to lading that is in conflict with these goals. In specific
14+
this means that lading will pre-allocate where possible, will explicitly thread
15+
randomness and other sources of non-determinism into code paths and will
16+
preference algorithms that have better worst-case behavior.
17+
18+
# Code Style
19+
20+
This project is subject attempts to automate code style to a great degree, using
21+
these tools:
22+
23+
* `cargo clippy`
24+
* `cargo fmt`
25+
26+
We do not allow for warnings: all warnings are errors. Deprecation warnings MUST
27+
be treated as errors. Lading is written in a "naive" style where abstraction is
28+
not preferred if a duplicated pattern will satisfy. Our reasoning for this is it
29+
makes ramp-up for new engineers easier: all you must do is follow the pattern,
30+
not internalize a complex type hierarchy. There are obvious places in the code
31+
base where replicated patterns have been made into abstractions -- we follow the
32+
"shape" rule, if you have three or more repeats, make a jig -- but we do not
33+
start there.
34+
35+
Lading is written to be as easy to contribute to as possible. We ask that any
36+
dependency used in the project in more than one crate be present in the
37+
top-level Cargo.toml and be referenced from the workspace in sub-crates.
38+
39+
Lading does not care about inward backward compatibility. Behavior observable to
40+
users must be preserved, but our internal APIs are not subject to backward
41+
compatibility concerns.
42+
43+
Lading project uses comments strategically, documenting the "why" and not the
44+
"what". Do not add "what" comments that put into English the behavior of a line
45+
or two of code. Do add comments that explain the "why" of a block of code, how
46+
it functions or is unusual in a way that an experienced engineer might not
47+
understand.
48+
49+
Crate versions are always given as XX.YY and not XX.YY.ZZ.
50+
51+
# Testing
52+
53+
Where possible lading prefers property tests over unit tests and in especially
54+
critical components we require proofs. We use
55+
[proptest](https://github.com/proptest-rs/proptest) in this project for property
56+
tests and the [kani](https://github.com/model-checking/kani) proof tool.
57+
58+
## Workflow
59+
60+
Changes to lading are subject this flow:
61+
62+
* `cargo check`
63+
* `cargo clippy`
64+
* `cargo nextest run`
65+
66+
Proofs must be run with the `cargo kani` tool in the crate where proofs reside.
67+
68+
69+
# Tools
70+
71+
To identify outdated dependencies: `cargo outdated --root-deps-only`.
72+
73+
To run micro-benchmarks: `cargo criterion`

0 commit comments

Comments
 (0)