diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..1772d53
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,23 @@
+# RSS Reader Project Guidelines
+
+## Build & Run Commands
+- Run demo mode: `just run-local-demo`
+- Run with database: `just run-local-persistant-db`
+- Run with Nix: `just run-local-nix`
+- Migrations: `just sqlx-prepare`
+- Production: `cargo run -- -d database.sqlite -p port`
+
+## Style Guidelines
+- **Imports**: Group by source (std lib, external crates, internal modules)
+- **Naming**: snake_case for variables/functions, CamelCase for types
+- **Documentation**: Use `///` doc comments for public items
+- **Error Handling**: Use Result types with detailed error messages
+- **Types**: Leverage Rust's type system fully, minimize `unwrap()`
+- **Formatting**: Follow standard Rust formatting with 4-space indentation
+
+## Project Architecture
+- Web framework: Rocket with SQLite database
+- Templates: Tera templates
+- Authentication: Argon2/bcrypt password hashing
+- Frontend: HTML/CSS with Vite for asset bundling
+- Feed handling: RSS/Atom parsing with feed-rs
\ No newline at end of file