docs(agents): branching strategy, component-test Docker note, set-based Cypher writes

Merged
PA
4mo ago
+54-6

Summary

Three small context improvements from the IFC-2867 session retrospective (PR #10000):

  • Branching (new AGENTS.md section): feature/bugfix branches start from develop; verify the code a ticket references exists on the chosen base before cutting a branch โ€” the session first cut its branch off stable, where the referenced module doesn't exist yet.
  • Component tests & Docker (AGENTS.md testing section): backend/tests/component/ needs a running Docker daemon, and testcontainers only looks at /var/run/docker.sock โ€” documented the DOCKER_HOST override for daemons exposing a user socket only.
  • Set-based Cypher writes (neo4j-cypher-guide skill): prefer one conditioned write query over fetch-then-mutate-each (N+1) โ€” a reviewer had to point this out on #10000.

๐Ÿค– Generated with Claude Code


Summary by cubic

Clarifies branching rules, documents Docker needs for component tests, and expands the Neo4j Cypher guide with set-based writes and dynamic label/type guidance. Also links the backend feature checklist, tightens exception handling guidance, and updates changelog/docs rules (IFC-2867 follow-up).

  • Guideline updates
    • Branching in dev/guidelines/git-workflow.md: features from develop; bug fixes to the oldest affected branch; verify the base contains the code.
    • Component tests: default path needs a Docker daemon; set INFRAHUB_USE_TEST_CONTAINERS=false to reuse an existing DB.
    • Backend docs: link dev/guidelines/backend/checklist.md; add an exception-hierarchy note; fix the coding-standards list glitch.
    • Cypher guide: add set-based write guidance and dynamic labels/types ($($param), Neo4j 5.26+) with planner/plan-cache tradeoffs.
    • Changelog/docs: skip fragments for fixes to unreleased features; avoid ticket/spec IDs in documentation.