docs: Add AGENTS.md development guide

[Cristhianzl]

Objective

Add a single, authoritative development guide (AGENTS.md) that consolidates all coding standards, testing rules, and quality principles for the Langflow project.

---

Changes

• Add AGENTS.md to the project root as the unified reference for all AI agents and contributors.

---

Sections Covered

1. Core Philosophy

• Trade-off priority order:
  correctness > simplicity > testability > performance > abstraction
• Ground rules for incremental delivery

2. Design Principles

• SOLID principles (with practical rules and common mistakes)
• DRY (Rule of Three)
• KISS
• YAGNI

3. Code Quality

• Naming conventions
• Strong typing
• Immutability
• Early returns / guard clauses
• No magic values
• Comments focused on WHY, not WHAT

4. Architecture

• Separation of concerns
• Layer rules (CAN / CANNOT table for handlers, services, repositories, helpers)
• Dependency injection
• DDD (when justified)

5. File Structure

• ~500 line limit for production code
• Single responsibility per file
• Mandatory separation by responsibility prefix
• Anti over-engineering rules

6. Error Handling

• Fail fast
• Domain-relevant errors with context
• No silent failures
• No generic exceptions

7. Security

• Input validation with allowlists
• Parameterized queries
• No hardcoded secrets
• No PII in test data

8. Observability

• Structured logging (key-value / JSON)
• Consistent log levels: ERROR / WARN / INFO / DEBUG
• Zero tolerance for PII in logs

9. Testing

• Happy path and adversarial tests

• AAA pattern (Arrange, Act, Assert)

• Coverage target: 80% (minimum 75%)

• Mandatory coverage report execution

• Forbidden anti-patterns:

  • Liar
  • Mirror
  • Giant
  • Mockery
  • Inspector
  • Chain Gang
  • Flaky

10. Code Review

• Review priority order:
  security > DRY > structure > architecture > quality > testing
• Review questions for test quality
• Legacy code awareness

11. Documentation

• C4 model levels

• Required feature documentation sections:

  • Overview
  • Glossary
  • Domain model
  • BDD specs
  • ADRs
  • Technical specification
  • Observability
  • Deployment

12. Pre-Delivery Checklist

Complete checklist organized by categories:

• Critical (blockers)
• Important (must fix)
• Testing (mandatory)
• Quality (should fix)
• Pre-Commit (linter / formatter / type checker)

Summary by CodeRabbit

• Documentation
  • Added comprehensive development guide documenting coding standards, design principles, architecture conventions, error handling patterns, security guidelines, testing strategies, and pre-delivery checklists for maintaining code quality and project compliance.

[github-actions]

Frontend Unit Test Coverage Report

Coverage Summary

Lines	Statements	Branches	Functions
	19.03% (6177/32459)	12.53% (3175/25323)	12.75% (888/6962)

Unit Test Results

Tests	Skipped	Failures	Errors	Time
2345	0 💤	0 ❌	0 🔥	32.794s ⏱️

[Adam-Aghili]

LGTM! even if we don't merge this I am adding it to my local

[coderabbitai]

Important

Review skipped

Auto incremental reviews are disabled on this repository.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

Walkthrough

A new comprehensive Langflow Development Guide (AGENTS.md) has been added containing 490 lines of documentation covering coding standards, design principles, architecture conventions, error handling, security, observability, testing strategies, code review processes, documentation requirements, and pre-delivery checklists.

Changes

Cohort / File(s)	Summary
Development Guide AGENTS.md	New comprehensive guide establishing coding standards (SOLID, DRY, KISS, YAGNI principles), layered architecture patterns, dependency injection conventions, error handling strategies, structured logging requirements, testing approaches (including adversarial testing and coverage targets), documentation standards, and pre-delivery checklist for Langflow project.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

🚥 Pre-merge checks | ✅ 6 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Test File Naming And Structure	⚠️ Warning	AGENTS.md lacks explicit test file naming conventions and organizational structure patterns required as an authoritative reference.	Add 'Test File Naming and Organization' subsection documenting backend/frontend naming patterns, directory structure, and concrete examples.

✅ Passed checks (6 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'docs: Add AGENTS.md development guide' accurately summarizes the main change—adding a comprehensive development guide document to the repository.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Test Coverage For New Implementations	✅ Passed	AGENTS.md is documentation without new code features or bug fixes, validated through style review rather than unit tests.
Test Quality And Coverage	✅ Passed	PR adds only AGENTS.md documentation file with development guidelines; no functional code or implementations requiring test coverage.
Excessive Mock Usage Warning	✅ Passed	This PR only adds AGENTS.md documentation and configuration files, not actual test implementations. The custom check for excessive mock usage in test code is not applicable.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch cz/agent-rule

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 35.71%. Comparing base (655aee4) to head (4e057db).
⚠️ Report is 2 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main   #11922      +/-   ##
==========================================
- Coverage   35.71%   35.71%   -0.01%     
==========================================
  Files        1528     1528              
  Lines       73928    73928              
  Branches    11134    11134              
==========================================
- Hits        26407    26404       -3     
- Misses      46081    46085       +4     
+ Partials     1440     1439       -1     

Flag	Coverage Δ
backend	56.29% <ø> (-0.03%)	⬇️
frontend	17.18% <ø> (ø)
lfx	42.40% <ø> (+<0.01%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.
see 5 files with indirect coverage changes

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[coderabbitai]

Actionable comments posted: 2

🧹 Nitpick comments (1)

AGENTS.md (1)

277-300: Consider explicitly mentioning structlog in the observability section.

The section correctly emphasizes structured logging with key-value pairs and consistent field names. Since Langflow uses structlog throughout the codebase, explicitly mentioning it here would provide concrete guidance aligned with the project's actual implementation.

💡 Suggested enhancement

 ### Logging
 
-Use structured logging (key-value / JSON), not formatted strings.
+Use structured logging (key-value / JSON), not formatted strings. Langflow uses `structlog` for all logging.
 - Log at key decision points and boundaries, not inside tight loops.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@AGENTS.md` around lines 277 - 300, Update the Observability -> Logging
section to explicitly mention that the project uses structlog for structured
logging; add a short sentence after "Use structured logging (key-value / JSON),
not formatted strings." saying "We use structlog across the codebase — follow
its key/value logging patterns and configured processors (see structlog config)
for consistent fields." Reference structlog by name and recommend using the
project's structlog configuration and approved identifier fields (`auth_id`,
`user_id`, `internal_id`) when emitting logs.

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@AGENTS.md`:
- Around line 216-231: Add a language specifier to the Markdown code fence that
contains the module structure (the fenced block starting with "feature/" and the
tree lines) so it renders with proper syntax highlighting and complies with
Markdown; update the opening fence from ``` to something like ```text (or
another appropriate language) and leave the block contents unchanged.
- Around line 245-258: Replace the generic logging example that uses
logger.warning with an extra parameter by demonstrating the project's structlog
usage: import structlog, obtain a logger via structlog.get_logger(__name__), and
emit a structured event (e.g., logger.warning("validation_failed", error=str(e),
field=e.field)) inside the ValidationError except block before raising
DomainError; keep the surrounding example (do_something(), ValidationError,
DomainError) but update the logging call to the structlog pattern and remove the
extra={"..."} usage.

---

Nitpick comments:
In `@AGENTS.md`:
- Around line 277-300: Update the Observability -> Logging section to explicitly
mention that the project uses structlog for structured logging; add a short
sentence after "Use structured logging (key-value / JSON), not formatted
strings." saying "We use structlog across the codebase — follow its key/value
logging patterns and configured processors (see structlog config) for consistent
fields." Reference structlog by name and recommend using the project's structlog
configuration and approved identifier fields (`auth_id`, `user_id`,
`internal_id`) when emitting logs.

---

ℹ️ Review info

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 655aee4 and e8d1881.

📒 Files selected for processing (1)

• AGENTS.md