Add best-practices library, knowledge distillation pipeline settings, and first session log
- best-practices/: 11 topic files + INDEX.md extracted from cluster-bootstrap and custom-claude-skills (validation, k8s, helm, ansible, secrets, debugging, etc.) - settings.yaml: pipeline config (log retention, tracked projects, max logs per run) - CLAUDE.md: updated with best-practices loading and pipeline documentation - memory/log/: first session log demonstrating the format Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
41
best-practices/debugging.md
Normal file
41
best-practices/debugging.md
Normal file
@@ -0,0 +1,41 @@
|
||||
# Debugging Methodology
|
||||
|
||||
## Check Before You Act
|
||||
|
||||
- Before writing firewall/network rules, check actual routing (`ip route get <dest>`)
|
||||
- Before running config management with variables, ensure values are real, not placeholders
|
||||
- Before assuming a container has a shell, `docker inspect` it
|
||||
- Before creating API tokens, research all required scopes upfront — iterating one scope at a time costs a push-debug cycle each
|
||||
|
||||
## Routing and Networking
|
||||
|
||||
- Always run `ip route get <dest>` on the forwarding host first
|
||||
- macvlan, Docker bridge, and other virtual interfaces mean the "obvious" physical interface is often wrong
|
||||
- Test from both in-cluster and external perspectives
|
||||
|
||||
## Full-Chain Testing
|
||||
|
||||
After wiring up any new service:
|
||||
1. Test direct to backend (bypass all proxies)
|
||||
2. Test through reverse proxy (bypass DNS)
|
||||
3. Test end-to-end as a user would
|
||||
|
||||
Use `curl --resolve` to test specific paths without depending on DNS propagation.
|
||||
|
||||
## When Something Doesn't Sync/Apply
|
||||
|
||||
- Check resource exclusions in the GitOps controller immediately
|
||||
- Check if the resource type requires special permissions or labels
|
||||
- Check if ServerSideApply conflicts are preventing field changes
|
||||
- Don't try workarounds before understanding the root cause
|
||||
|
||||
## OIDC Integration Checklist
|
||||
|
||||
Before starting any OIDC integration, research:
|
||||
1. What format is the `sub` claim (UUID? username?)
|
||||
2. Which claims are in the ID token vs userinfo endpoint
|
||||
3. How the consumer matches RBAC identities (groups? email? username?)
|
||||
|
||||
## Grep Your Own Docs
|
||||
|
||||
Known issues documented in CLAUDE.md or MEMORY.md but not applied to new scripts/configs waste debugging time. Search your own documentation before writing automation that touches areas with known gotchas.
|
||||
Reference in New Issue
Block a user