diff --git a/README.md b/README.md
index 5b2b555..bf5359e 100644
--- a/README.md
+++ b/README.md
@@ -24,6 +24,8 @@ To run tests, execute from the root directory:
 busted
 ```
 
+Writing specs is a bit more complicated. Check out [the spec writing guide](spec/README.md).
+
 ## License (MIT)
 
 Copyright (C) 2015 by Leaf Corcoran
diff --git a/spec/README.md b/spec/README.md
new file mode 100644
index 0000000..67a99a0
--- /dev/null
+++ b/spec/README.md
@@ -0,0 +1,58 @@
+
+# MoonScript Spec guide
+
+Because MoonScript is written in MoonScript, and MoonScript specs are written
+in MoonScript, you need to be aware of which copy of MoonScript is actually
+executing the specs.
+
+A system installed version of MoonScript is recommended to run the specs (and
+for development). This means that you'll typically have two versions of
+MoonScript available in the load path:
+
+* The system version
+* The version in the current directory
+
+> A system install is recommended because you'll always want a functioning
+> version of MoonScript to compile with in case you break your development
+> version.
+
+When developing you want to make ensure the tests are executing your changes in
+the current directory, and not testing the system install.
+
+Code running in Busted will have the system install take precedence over the
+loaded version. That means that if you `require "moonscript.base"` for a test,
+you won't get the local copy.
+
+The `with_dev` spec helper will ensure that any require calls within the spec
+that ask for MoonScript modules. `with_dev` calls a setup and teardown that
+replaces `_G.require` with a custom version.
+
+You'll use it like this:
+
+```moonscript
+import with_dev from require "spec.helpers"
+describe "moonscript.base", ->
+  local moonscript
+
+  with_dev!
+
+  it "should load code", ->
+    -- the local version is loaded
+    moonscript = require "moonscript"
+    moonscript.load "print 12"
+```
+
+
+`with_dev`'s require function will load the `.lua` files in the local
+directory, not the `moon` ones. You're responsible for compiling them first
+before running the tests.
+
+You might do
+
+```bash
+$ make compile_system; busted
+```
+
+> `make compile_system` is a makefile task included in the repo that will build
+> MoonScript in the current directory with the version installed to the system
+