chore: Add CLAUDE.md to register code standards with Claude agent#183
chore: Add CLAUDE.md to register code standards with Claude agent#183morgan-wowk wants to merge 1 commit intomasterfrom
Conversation
|
|
||
| - **Derive schema metadata from models.** Never hardcode table names, column names, or column types as strings. Reference them from the SQLAlchemy model (e.g. `Model.__table__.c.column_name`) and compile types with `col.type.compile(dialect=engine.dialect)`. | ||
| - **Single transaction per logical operation.** Wrap all related DDL or DML mutations in one `with engine.connect() as conn` / `conn.commit()` block. | ||
| - **Log migrations.** Every migration step (ALTER TABLE, backfill, index creation) should log before it runs and handle `OperationalError` for concurrent deployments gracefully. |
There was a problem hiding this comment.
Catch errors and log them.
There was a problem hiding this comment.
Great suggestion — updated the "Log migrations" rule to explicitly include catching and logging exceptions. Thanks!
| - **f-strings for all logging.** Use `_logger.info(f"...")` — never `%s` interpolation. | ||
| - **Keyword-only arguments.** Add `*` to function definitions to make all parameters keyword-only, even when there is only one parameter. | ||
| - **Unused parameters.** Prefix unused function parameters with `_` (e.g. `_old_value`, `_initiator`) and add type hints to every parameter, used or not. | ||
| - **StrEnum for known string sets.** When a parameter or constant is drawn from a fixed set of strings, define a `StrEnum` for it rather than using bare string literals. |
There was a problem hiding this comment.
- Type hinting function parameters
- Import modules only except for exception of
from typing import ... - python filenames should:
Style: Modules should be names as plural or uncountable nouns.
Example: database_migrations.py instead of database_migrate.py
There was a problem hiding this comment.
All three added — type hints on every function parameter/return type, module-only imports (with the from typing import exception), and plural/uncountable noun file naming. Thanks for the detailed suggestions!
morgan-wowk
force-pushed
the
claude-rules
branch
from
973a82f to
c130d15
Compare
|
|
||
| - **f-strings for all logging.** Use `_logger.info(f"...")` — never `%s` interpolation. | ||
| - **Keyword-only arguments.** Add `*` to function definitions to make all parameters keyword-only, even when there is only one parameter. | ||
| - **Unused parameters.** Prefix unused function parameters with `_` (e.g. `_old_value`, `_initiator`) and add type hints to every parameter, used or not. |
There was a problem hiding this comment.
Hmm. I'm not sure we [should] do that. Parameter names should not be changed (breaking change) and when creating a function, there should not be any unused parameters. The only case where there can be some unused parameters is when implementing and interface. But in that case the parameter names must match the interface.
There are couple of places where I've used underscored parameters to mean private/internal, although this is not ideal.
There was a problem hiding this comment.
I will remove this line. It stemmed from an interface implementation I'm pretty sure but I don't remember exactly anymore.
3 participants
TL;DR
Added coding conventions documentation for Python, SQLAlchemy, and data safety practices.
What changed?
Created
CLAUDE.mdfile containing development guidelines including:How to test?
No testing required - this is documentation only. Developers should reference these conventions when writing new code or reviewing pull requests.
Why make this change?
Establishes consistent coding standards across the repository to improve code quality, maintainability, and prevent data loss incidents during development.