Skip to content

feat: cross-cutting development conventions from post-v0.2.0 learnings #1342

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
jeremyeder merged 2 commits into from
Apr 17, 2026
+17 −1
Merged

feat: cross-cutting development conventions from post-v0.2.0 learnings #1342

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
a73e104
feat: add cross-cutting development conventions from post-v0.2.0 lear…
Apr 17, 2026
cc45dcf
chore: remove triage dashboard from PR (local-only artifact)
Apr 17, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
18 changes: 17 additions & 1 deletion CLAUDE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -90,7 +90,8 @@ Benchmark notes:

## Critical Conventions

Rules that apply across ALL components. Per-component details live in component DEVELOPMENT.md files.
Cross-cutting rules that apply across ALL components. Component-specific conventions live in
component DEVELOPMENT.md files (see [BOOKMARKS.md](BOOKMARKS.md) > Component Development Guides).

- **User token auth required**: All user-facing API ops use `GetK8sClientsForRequest(c)`, never the backend service account
- **No tokens in logs/errors/responses**: Use `len(token)` for logging, generic messages to users
Expand All @@ -99,6 +100,21 @@ Rules that apply across ALL components. Per-component details live in component
- **No `any` types in frontend**: Use proper types, `unknown`, or generic constraints
- **Feature flags strongly recommended**: Gate new features behind Unleash flags. Use `/unleash-flag` to set up
- **Conventional commits**: Squashed on merge to `main`
- **Design for extensibility before adding items**: When building infrastructure that will have
things added to it (menus, config schemas, API surfaces), build the extensibility mechanism
first — conditional rendering, feature-flag gating, discovery. Retrofitting causes rework.
- **Verify contracts and references**: Before building on an assumption (env var exists, path is
correct, URL is reachable), verify the contract. After moving anything, grep scripts, workflows,
manifests, and configs — not just source code.
- **CI/CD security**: Never use `pull_request_target` (grants write access to forked PR code).
Never hardcode tokens — use `actions/create-github-app-token`. For automated pipelines:
discovery → validation → PR → auto-merge.
- **Full-stack awareness**: Before building a new pipeline, check if an existing one can be
reused. Auth/credential/API changes must update ALL consumers (backend, CLI, SDK, runner,
sidecar) in the same PR.
- **Separate configuration from code**: Config changes must not require code changes. Externalize
via env vars, ConfigMaps, manifests, or feature flags. If a value varies across environments
or changes over time, it's config, not code.

Component-specific conventions:
- Backend: [DEVELOPMENT.md](components/backend/DEVELOPMENT.md), [ERROR_PATTERNS.md](components/backend/ERROR_PATTERNS.md), [K8S_CLIENT_PATTERNS.md](components/backend/K8S_CLIENT_PATTERNS.md)
Expand Down