e94417b896
Includes: spec-driven and test-driven development best practices, reproduce-before-fixing debugging workflow, require-plan-file hook, find-project-root script, session logs, memory files for decisions/ gotchas/process-lessons, and updates to existing best practice topics. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
1.9 KiB
1.9 KiB
Git & Source Control
Commit Practices
- Use meaningful commit messages; prefer small, focused commits over large batches
- Never commit secrets in plaintext — use SOPS + age or equivalent encryption
- Enable pre-commit hooks where appropriate (secret detection, linting, formatting)
Pre-Commit Hooks
- Block
local_secrets/and similar directories from being committed - Auto-encrypt files matching
.sops.yamlrules that aren't yet encrypted - Enable with
git config core.hooksPath .githooks - Consider secret detection, linting, and formatting hooks
GitOps Workflow
- All infrastructure changes should be tracked in Git
- No manual changes without corresponding GitOps manifests — anything applied manually (e.g.,
kubectl apply,helm install) should immediately get a corresponding tracked manifest - For ArgoCD-managed clusters: edit in Git, push, sync — never edit live resources directly
Remote Conventions
- SSH workflows preferred over HTTPS for Git remotes
- Use SSH config host aliases for multi-user setups (e.g.,
gitea.example.com-<user>) - Remote URL format:
git@<host-alias>:<org>/<repo>.git - Optionally push-mirror to GitHub for public visibility
Access and Clone Gotchas
- Org repos require explicit collaborator grants. Don't assume organizational membership implies write access — verify permissions before setting up automation or CI/CD.
- Shallow clones break push operations.
git clone --depth 1is fine for read-only CI jobs, but pipelines that push artifacts, tags, or mirror to other remotes need full clones.
Version Management
- Use the latest stable version of dependencies unless pinned for a reason
- Verify versions from live sources (
helm search repo, upstream docs, package registries) — don't rely on memory - Document the reason in a comment if a version is intentionally pinned below latest
- Check compatibility matrices before upgrading (e.g., Talos ↔ Kubernetes, framework ↔ runtime)