Contributing
Coding Standards
The architectural, framework and coding standards for engineering at ESProfiler. This is to help define the scope of what we use and how we use it for AI and Engineers. This is a work in progress and not exhaustive.
Agent Usage
AGENTS.md vs CLAUDE.md
Most coding harnesses support AGENTS.md by default
- AGENTS.md
- default place for all repo based agent instructions
- CLAUDE.md
- put @AGENTS.md as the first line of the repo CLAUDE.md
- add another line instructing claude to maintain any additional instructions in AGENTS.md
AGENTS.md vs README.md files
- AGENTS.md should be used for architectural and coding decision information, so is targeted at AI and developers
- README.md should only be for repo usage information, so is targetted at a user
PRs
Target the reviewer
When creating a PR, the description content:
- should contain details targetted to the level of knowledge of the reviewer
- should not contain AI generated content that is overly verbose and overly technical. These are difficult to read and understand. You can use AI but make sure you edit it, to be more consumable by a human reviewer.
- should use
<details>tags to collapse large additional information blocks e.g. example JSON or images - should not be longer than a single screen, use
<details>tags for extra detail
Dependencies
- Include links to dependent PRs at the bottom of the PR description
Frontend Standards
- Main Repo
- Languages
- Typescript
- Tooling
- Vite
- Vitest
- Cypress
- Storybook 10
- oxlint
- ESLint
- Posthog
- Github actions
- Frameworks
- Vue
- Nuxt.js
- amCharts
- Tiptap
- Monaco
- GrapesJS
- Tailwind
- Vercel AI SDK
Backend Standards
- Main Repo
- https://github.com/ES-Profiler/platform-api
- there are many other API repos
- Languages
- Java 25+ using GraalVM
- Tooling
- Maven - using mvnd
- Langfuse
- Github actions
- Frameworks
- Liquibase - for SQL migrations
- Spring Boot 4.x
- Spring Cloud
- Spring AI
- Hibernate - with Envers for entity audit history
- StringTemplate (.st) - Used to for specifying LLM prompts - main prompt library is in https://github.com/ES-Profiler/esp-prompts
- LLMs
- Gemini 3.5 flash
- Gemini 3.7 flash
- Data Storage
- MySQL - main database
- Postgres - only pgvector for vector search
Data Engineering & Data Science Standards
- Main Repo
- https://github.com/ES-Profiler/data-science
- many other data related repos
- Languages
- Python
- Tooling
- n8n - agentic workflows - deprecated
- Langfuse
- pytest
- ruff - formatting & linting
- Frameworks
- Streamlit - interactive UI for analysing experiments/tests
- Httpx - for interacting with APIs
- LLMs
- Gemini 3.5 flash
- Gemini 3.7 flash
- Data Storage
- Sqlite3 - Local experiment tracking databases
Devops
- Alloy
- Langfuse
- Posthog

