From f30fbf0f6859da24e638d8bc2d82d5633ddccfa4 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=C3=81lvaro=20Gonz=C3=A1lez?=
 <alvarogonzalezsotillo@gmail.com>
Date: Thu, 21 Aug 2025 16:47:21 +0200
Subject: [PATCH] Added guidelines for agents from
 https://www.dzombak.com/blog/2025/08/getting-good-results-from-claude-code/

---
 CLAUDE.md | 153 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 README.md |  33 ++++++++++++
 2 files changed, 186 insertions(+)
 create mode 100644 CLAUDE.md

diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..856b497
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,153 @@
+# Development Guidelines
+
+## Philosophy
+
+### Core Beliefs
+
+- **Incremental progress over big bangs** - Small changes that compile and pass tests
+- **Learning from existing code** - Study and plan before implementing
+- **Pragmatic over dogmatic** - Adapt to project reality
+- **Clear intent over clever code** - Be boring and obvious
+
+### Simplicity Means
+
+- Single responsibility per function/class
+- Avoid premature abstractions
+- No clever tricks - choose the boring solution
+- If you need to explain it, it's too complex
+
+## Process
+
+### 1. Planning & Staging
+
+Break complex work into 3-5 stages. Document in `IMPLEMENTATION_PLAN.md`:
+
+```markdown
+## Stage N: [Name]
+**Goal**: [Specific deliverable]
+**Success Criteria**: [Testable outcomes]
+**Tests**: [Specific test cases]
+**Status**: [Not Started|In Progress|Complete]
+```
+- Update status as you progress
+- Remove file when all stages are done
+
+### 2. Implementation Flow
+
+1. **Understand** - Study existing patterns in codebase
+2. **Branch** - Create a new branch from current branch, asing a memorable name to the new branch
+3. **Test** - Write test first (red)
+4. **Implement** - Minimal code to pass (green)
+5. **Refactor** - Clean up with tests passing
+6. **Commit** - With clear message linking to plan
+
+### 3. When Stuck (After 3 Attempts)
+
+**CRITICAL**: Maximum 3 attempts per issue, then STOP.
+
+1. **Document what failed**:
+   - What you tried
+   - Specific error messages
+   - Why you think it failed
+
+2. **Research alternatives**:
+   - Find 2-3 similar implementations
+   - Note different approaches used
+
+3. **Question fundamentals**:
+   - Is this the right abstraction level?
+   - Can this be split into smaller problems?
+   - Is there a simpler approach entirely?
+
+4. **Try different angle**:
+   - Different library/framework feature?
+   - Different architectural pattern?
+   - Remove abstraction instead of adding?
+
+## Technical Standards
+
+### Architecture Principles
+
+- **Composition over inheritance** - Use dependency injection
+- **Interfaces over singletons** - Enable testing and flexibility
+- **Explicit over implicit** - Clear data flow and dependencies
+- **Test-driven when possible** - Never disable tests, fix them
+
+### Code Quality
+
+- **Every commit must**:
+  - Compile successfully
+  - Pass all existing tests
+  - Include tests for new functionality
+  - Follow project formatting/linting
+
+- **Before committing**:
+  - Run formatters/linters
+  - Self-review changes
+  - Ensure commit message explains "why"
+
+### Error Handling
+
+- Fail fast with descriptive messages
+- Include context for debugging
+- Handle errors at appropriate level
+- Never silently swallow exceptions
+
+## Decision Framework
+
+When multiple valid approaches exist, choose based on:
+
+1. **Testability** - Can I easily test this?
+2. **Readability** - Will someone understand this in 6 months?
+3. **Consistency** - Does this match project patterns?
+4. **Simplicity** - Is this the simplest solution that works?
+5. **Reversibility** - How hard to change later?
+
+## Project Integration
+
+### Learning the Codebase
+
+- Find 3 similar features/components
+- Identify common patterns and conventions
+- Use same libraries/utilities when possible
+- Follow existing test patterns
+
+### Tooling
+
+- Use project's existing build system
+- Use project's test framework
+- Use project's formatter/linter settings
+- Don't introduce new tools without strong justification
+
+## Quality Gates
+
+### Definition of Done
+
+- [ ] Tests written and passing
+- [ ] Code follows project conventions
+- [ ] No linter/formatter warnings
+- [ ] Commit messages are clear
+- [ ] Implementation matches plan
+- [ ] No TODOs without issue numbers
+
+### Test Guidelines
+
+- Test behavior, not implementation
+- One assertion per test when possible
+- Clear test names describing scenario
+- Use existing test utilities/helpers
+- Tests should be deterministic
+
+## Important Reminders
+
+**NEVER**:
+- Use `--no-verify` to bypass commit hooks
+- Disable tests instead of fixing them
+- Commit code that doesn't compile
+- Make assumptions - verify with existing code
+
+**ALWAYS**:
+- Commit working code incrementally
+- Update plan documentation as you go
+- Learn from existing implementations
+- Stop after 3 failed attempts and reassess
diff --git a/README.md b/README.md
index d825cab..39e8a81 100644
--- a/README.md
+++ b/README.md
@@ -2,6 +2,39 @@
 
 A comprehensive command-line application for managing and computing mathematical formulas across various disciplines including mathematics, physics, medicine, and engineering.
 
+# Development guidelines
+If you are a contributor or an agent, please follow [CLAUDE.md](./CLAUDE.md) for development guidelines
+
+# Formula file description
+
+The file is a json array of formulas.
+
+```json
+[
+    {
+        "name": "Newton's second law (scalar)",
+        "input": {
+            "m" : {
+               "magitude": "mass"
+            },
+            "a" : {
+               "magnitude": "acceleration"
+            }
+        },
+        "output": {
+            "F" : {
+                "magnitude" : "Force"
+            }
+        },
+        "d4rt_code":{
+            "return m*a;"
+        }
+    }
+
+]
+
+```
+
 ## Features
 
 ### Formula Search and Computation