chore: Add CLAUDE.md to register code standards with Claude agent#183
Open
morgan-wowk wants to merge 1 commit intomasterfrom
Open
chore: Add CLAUDE.md to register code standards with Claude agent#183morgan-wowk wants to merge 1 commit intomasterfrom
morgan-wowk wants to merge 1 commit intomasterfrom
Conversation
yuechao-qin
requested changes
Mar 20, 2026
CLAUDE.md
Outdated
|
|
||
| - **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. |
Collaborator
There was a problem hiding this comment.
Catch errors and log them.
Collaborator
Author
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. |
Collaborator
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
Collaborator
Author
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
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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.