diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..3b71f83
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,28 @@
+# NixCfg Development Guidelines
+
+## Build and Configuration Commands
+- Update NixOS: `nixos-rebuild --flake .#[hostname] switch`
+- Update Darwin: `darwin-rebuild --flake .#[hostname] switch`
+- Update Home Manager: `home-manager --flake .#[user]@[hostname] switch`
+- Format code: `nix fmt` (uses nixfmt-rfc-style)
+- Check configuration: `nix flake check`
+
+## Repository Structure
+- `modules/` - Reusable configuration modules
+- `systems/` - System-specific configurations
+- `homes/` - Home Manager user configurations
+- `lib/` - Helper functions and utilities
+
+## Style Guidelines
+- Use `metacfg` namespace for all options
+- Follow existing module structure: always use `mkEnableOption` + `mkIf` pattern
+- Naming: use kebab-case for files/directories, camelCase for options
+- Keep system-specific config in appropriate directories, extract common functionality to modules
+- Include sufficient documentation in code for complex functions
+- Commit messages should follow conventional commit format
+
+## Module Creation 
+- Create new modules in appropriate category under modules/
+- Use existing modules as templates for structure
+- Always define options with types and descriptions
+- Prefer using existing NixOS/Home Manager modules over custom implementations
\ No newline at end of file