Style Guide

The authoritative coding conventions live in the repository, in .claude/rules/. They apply to human and AI-assisted contributions alike:

File

Covers

code-quality.md

maintainability, DRY, commenting

go-rules.md

Go standards, test layout, AWS SDK mocking

backend.md

API handler conventions, DB-vs-handler boundary

aws-rules.md

CDK layout, IAM, DynamoDB patterns

git-flow.md

branches, commits, PRs

Go

  • Unit tests are Ginkgo v2 + Gomega, in *_test.go next to the code. Every behavior needs negative cases too — error paths, permission denials, malformed input.

  • AWS SDK calls go through the interface/mock layout in src/utils and src/mock so they stay testable.

  • RBAC checks belong in the DB layer, not scattered through handlers.

CDK / Python

  • Stacks follow the cdk/apps + cdk/libs layout; reuse app_common.py; one stack.py per lambda.

  • IAM grants are least-privilege. Every AWS SDK call needs a matching policy statement scoped to the specific resource. Wildcards need a comment explaining why the API requires one — *All grant helpers are not used.

General

  • Comment the why, not the what — and only when it is non-obvious.

  • Match the style of the surrounding code: naming, comment density, idiom.

  • Keep changes focused; don’t reformat or refactor code unrelated to your change in the same commit.