diff --git a/docs/compose-file.md b/docs/compose-file.md
index b55f250a8..0f1fccb31 100644
--- a/docs/compose-file.md
+++ b/docs/compose-file.md
@@ -274,6 +274,11 @@ beginning with `#` (i.e. comments) are ignored, as are blank lines.
     # Set Rails/Rack environment
     RACK_ENV=development
 
+> **Note:** If your service specifies a [build](#build) option, variables
+> defined in environment files will _not_ be automatically visible during the
+> build. Use the [args](#args) sub-option of `build` to define build-time
+> environment variables.
+
 ### environment
 
 Add environment variables. You can use either an array or a dictionary. Any
@@ -293,6 +298,11 @@ machine Compose is running on, which can be helpful for secret or host-specific
       - SHOW=true
       - SESSION_SECRET
 
+> **Note:** If your service specifies a [build](#build) option, variables
+> defined in `environment` will _not_ be automatically visible during the
+> build. Use the [args](#args) sub-option of `build` to define build-time
+> environment variables.
+
 ### expose
 
 Expose ports without publishing them to the host machine - they'll only be