diff --git a/AGENTS.md b/AGENTS.md
index ba19eee..1d29848 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -196,6 +196,65 @@ $: sound("hh*8").sometimes(rev).often(x => x.gain(0.5))
 
 - **Use lowercase commit messages**: All commit messages must be written in lowercase
 
+### Development Environment Guidelines
+
+- **Never use global npm installs**: Avoid `npm i -g` or `npm install -g` commands
+- **Use NixOS shells/dev environments**: Always prefer Nix-based development environments for reproducible builds
+- **Current NixOS version**: 25.05
+
+#### Nix Development Shell
+
+Use the following `flake.nix` for Strudel development:
+
+```nix
+{
+  description = "Strudel development environment";
+
+  inputs = {
+    nixpkgs.url = "github:NixOS/nixpkgs/nixos-25.05";
+    flake-utils.url = "github:numtide/flake-utils";
+  };
+
+  outputs = { self, nixpkgs, flake-utils }:
+    flake-utils.lib.eachDefaultSystem (system:
+      let
+        pkgs = nixpkgs.legacyPackages.${system};
+      in
+      {
+        devShells.default = pkgs.mkShell {
+          buildInputs = with pkgs; [
+            nodejs_20
+            pnpm
+            git
+          ];
+
+          shellHook = ''
+            echo "Strudel development environment loaded"
+            echo "Node.js: $(node --version)"
+            echo "pnpm: $(pnpm --version)"
+          '';
+        };
+      });
+}
+```
+
+#### Usage
+
+1. **Enter development shell**:
+   ```bash
+   nix develop
+   ```
+
+2. **Install dependencies**:
+   ```bash
+   pnpm install
+   ```
+
+3. **Start development server**:
+   ```bash
+   pnpm dev
+   ```
+
 ### Live Performance Considerations
 
 When creating beats for live performance:
diff --git a/flake.nix b/flake.nix
new file mode 100644
index 0000000..4ff57c8
--- /dev/null
+++ b/flake.nix
@@ -0,0 +1,29 @@
+{
+  description = "Strudel development environment";
+
+  inputs = {
+    nixpkgs.url = "github:NixOS/nixpkgs/nixos-25.05";
+    flake-utils.url = "github:numtide/flake-utils";
+  };
+
+  outputs = { self, nixpkgs, flake-utils }:
+    flake-utils.lib.eachDefaultSystem (system:
+      let
+        pkgs = nixpkgs.legacyPackages.${system};
+      in
+      {
+        devShells.default = pkgs.mkShell {
+          buildInputs = with pkgs; [
+            nodejs_20
+            pnpm
+            git
+          ];
+
+          shellHook = ''
+            echo "Strudel development environment loaded"
+            echo "Node.js: $(node --version)"
+            echo "pnpm: $(pnpm --version)"
+          '';
+        };
+      });
+}
\ No newline at end of file