diff --git a/.circleci/config.yml b/.circleci/config.yml
index e05ab85a..c21a7ff0 100644
--- a/.circleci/config.yml
+++ b/.circleci/config.yml
@@ -1,5 +1,12 @@
 version: 2
 
+# global environment variables
+# '& ' syntax is a YAML thing for creating referenceable documents
+env-shared: &env-shared
+  environment:
+    GOFLAGS: "-mod=vendor"
+
+# build steps shared across different jobs
 build-shared: &build-shared
   steps:
     - checkout
@@ -16,27 +23,39 @@ build-shared: &build-shared
     - run:
         name: Run tests
         command: |
-          go test -v -mod=vendor ./...
+          go test -v ./...
+    - run:
+        name: Get gox
+        # -mod=vendor doesn't work with go get while in source tree with go.mod in it
+        working_directory: "/tmp"
+        command: |
+          go get github.com/mitchellh/gox
     - run:
         name: Compile project on every platform
         command: |
-          go get github.com/mitchellh/gox
-          GOFLAGS=-mod=vendor gox -parallel 10 -os "linux freebsd" -osarch "darwin/i386 darwin/amd64"
+          gox -parallel 10 -os "linux freebsd" -osarch "darwin/i386 darwin/amd64"
     - save_cache:
         key: pkg-cache-{{ checksum "go.sum" }}-v5
         paths:
           - ~/.cache/go-build
 
 jobs:
+  # matrix build jobs run on every commit
+  # building on versioned Go and the latest one
+  # '<<: *' syntax is a YAML thing for including documents
   "golang:1.12":
+    <<: *env-shared
     <<: *build-shared
     docker:
       - image: circleci/golang:1.12
   "golang:latest":
+    <<: *env-shared
     <<: *build-shared
     docker:
       - image: circleci/golang:latest
+  # release job run only when a commit is tagged
   release:
+    <<: *env-shared
     docker:
       - image: circleci/golang:1.12
     steps:
@@ -68,6 +87,7 @@ workflows:
   version: 2
   build:
     jobs:
+      # build matrix
       - "golang:1.12"
       - "golang:latest"
   release: