diff --git a/HACKING.md b/HACKING.md
new file mode 100644
index 0000000000..c7266eafc8
--- /dev/null
+++ b/HACKING.md
@@ -0,0 +1,82 @@
+# Hacking CosmJS
+
+Welcome to CosmJS, glad to see you here. This document explains all you need to
+work on CosmJS, i.e. modify it. It is not intended for users of CosmJS.
+
+## Prerequisite
+
+- A UNIX-like development environment
+- Node.js 10+, Docker and yarn
+- `sha256sum`, which you
+  [can get on macOS as well](https://unix.stackexchange.com/questions/426837/no-sha256sum-in-macos)
+
+## Checking out code
+
+We use Git for version control. In addition to the well-known basics, we use the
+extension Git Large File Storage (LFS) to store blobs (currently \*.png and
+\*.wasm). A git-lfs package is available directly in modern package repositories
+(Debian 10+, Ubuntu 18.04+, Homebrew, MacPorts) and as a backport for older
+systems. Please see [this website](https://git-lfs.github.com/) for instructions
+how to install it.
+
+If you installed git-lfs after cloning this repo, use this command to replace
+the links with the original files: `git lfs checkout`.
+
+To verify everything worked as expected, check if the testing contracts are
+correctly checked out:
+
+```sh
+cd scripts/wasmd/contracts
+sha256sum -c checksums.sha256
+```
+
+## Running tests
+
+For unit tests that don't connect to any blockchain, just do:
+
+```sh
+yarn install
+yarn test
+```
+
+To run the entire test suite, you need to run some local blockchain to test
+against. We use [wasmd](https://github.com/CosmWasm/wasmd) for both CosmWasm
+tests and as a generic Cosmos SDK 0.38 blockchain. We also spawn multiple
+versions of raw Tendermint and a basic WebSocket server.
+
+```sh
+# Start wasmd
+./scripts/wasmd/start.sh
+./scripts/wasmd/init.sh
+export WASMD_ENABLED=1
+
+# Start Tendermint
+./scripts/tendermint/all_start.sh
+export TENDERMINT_ENABLED=1
+
+# Start WebSocket server
+./scripts/socketserver/start.sh
+export SOCKETSERVER_ENABLED=1
+
+# now more tests are running that were marked as "pending" before
+yarn test
+
+# And at the end of the day
+unset SOCKETSERVER_ENABLED
+unset TENDERMINT_ENABLED
+unset WASMD_ENABLED
+./scripts/socketserver/stop.sh
+./scripts/tendermint/all_stop.sh
+./scripts/wasmd/stop.sh
+```
+
+## Sanity
+
+After you modified a file, check if the linter is happy:
+
+```sh
+yarn lint
+
+# or if you want liniting plus automatic fixing
+yarn lint-fix
+```
diff --git a/README.md b/README.md
index f6e2f34562..b643bbb589 100644
--- a/README.md
+++ b/README.md
@@ -68,30 +68,4 @@ a higher level roadmap
 
 ## Development
 
-Requires Node 10+. For best results, use yarn. The basic commands are:
-
-```sh
-yarn install
-
-# compile the code
-yarn build
-# run unit tests
-yarn test
-
-# format and lint the code
-yarn format && yarn lint
-```
-
-### Integration tests
-
-To run the entire test suite, you need to run a local blockchain to test
-against. We use [wasmd](https://github.com/CosmWasm/wasmd) for both CosmWasm
-tests and as a generic Cosmos SDK 0.38 blockchain. This should work on any
-Linux/OSX system with docker installed:
-
-```sh
-./scripts/wasmd/start.sh
-./scripts/wasmd/init.sh
-WASMD_ENABLED=1 yarn test
-./scripts/wasmd/stop.sh
-```
+See [HACKING.md](HACKING.md).