DEV Community: David Paluy

Codex CLI Developer Guide

David Paluy — Mon, 29 Sep 2025 16:25:00 +0000

Quick Start
Resume Codex Sessions
Shell Shortcuts
Essential Configuration
- Recommended config.toml
Settings - Deep Dive
- Sandbox Modes
- Command-Line Overrides (-c flag)
- YOLO Mode (--yolo)
- Approval Policies
- Profiles for Different Workflows
- Verbosity - model_verbosity
- Network Access
- Environment Variables
Security Best Practices

Quick Start

Install Codex CLI

npm install -g @openai/codex@latest

verify installation

codex --version

codex login

Quick Examples

# Basic usage
codex "refactor this function to use dependency injection"

# With higher reasoning effort and detailed summary
codex -c model_reasoning_effort="high" -c model_reasoning_summary="detailed" "explain this complex algorithm"

# Automation in an isolated environment (bypasses sandbox/approvals)
codex --yolo "run tests and fix any failures"

# Generate Rails code when "dev" profile is defined
codex --profile dev "create a User model with devise authentication"

# Debug Rails issues
codex -c model_reasoning_effort="high" "fix this N+1 query in the users controller"

# Add features
codex "add pagination to the posts index using kaminari"

Resume Codex Sessions

Reopen your work. From the project directory you originally used, run:

   codex resume

Codex continues the last session where you left off so you can keep iterating immediately (Codex changelog).

Continue last session. Run codex resume --last to load the most recent conversation.

Shell Shortcuts

Keep frequently used flags close at hand with a reusable helper.

Add this to your .bashrc or .zshrc:

# Add to ~/.bashrc or ~/.zshrc
cdx() {
  local subcommand="$1"
  local base_model="gpt-5-codex"
  local base_args=(-m "$base_model" --search)

  if [[ -z "$subcommand" ]]; then
    codex "${base_args[@]}"
    return
  fi

  case "$subcommand" in
    help|-h|--help)
      cat <<'USAGE' >&2
Usage: cdx <prompt>
       cdx <subcommand> [args]

Subcommands:
  update                 install the latest Codex CLI
  5h                     high-effort reasoning run
  yolo                   run with --yolo (danger mode)
  dev|quick|auto|analyze switch to a named profile
USAGE
      return 0
      ;;
    update)
      npm install -g @openai/codex@latest
      ;;
    5h)
      shift
      codex -m gpt-5 -c model_reasoning_effort="high" --search "$@"
      ;;
    yolo)
      shift
      codex "${base_args[@]}" --yolo "$@"
      ;;
    dev|quick|auto|analyze)
      shift
      codex --profile "$subcommand" "$@"
      ;;
    *)
      codex "${base_args[@]}" "$@"
      ;;
  esac
}

Usage: cdx <prompt>
       cdx <subcommand> [args]

Subcommands:
  update                 install the latest Codex CLI
  5h                     high-effort reasoning run
  yolo                   run with --yolo (danger mode)
  dev|quick|auto|analyze switch to a named profile

examples

# Default dev workflow without bypassing safeguards
cdx "fix this N+1 query in the posts controller"

# Update Codex CLI
cdx update

# Switch to the dev profile on demand
cdx dev "implement OAuth authentication"

# High-reasoning call without yolo overrides
cdx 5h "optimize this complex SQL query with multiple joins"

# Explicitly opt into --yolo (automation-only)
cdx yolo "run tests and fix any failures"

Optional aliases

Add a few shortcuts after the function if you prefer profile-specific commands:

alias cdxdev='cdx dev'
alias cdxq='cdx quick'
alias cdxa='cdx auto'
alias cdxs='cdx analyze'

Essential Configuration

Recommended config.toml

Create ~/.codex/config.toml:

# Base settings
model = "gpt-5-codex"
model_provider = "openai"
sandbox_mode = "workspace-write"
approval_policy = "on-failure"
model_reasoning_effort = "high"

# Enable network for API calls and package installation
[sandbox_workspace_write]
network_access = true

# Safe environment variables
[shell_environment_policy]
inherit = "core"
experimental_use_profile = true

# Development profile
[profiles.dev]
model_reasoning_effort = "high"
model_verbosity = "high"
sandbox_mode = "workspace-write"
approval_policy = "on-failure"

# Quick tasks profile
[profiles.quick]
model_reasoning_effort = "low"
sandbox_mode = "workspace-write"
approval_policy = "never"

# Analysis profile
[profiles.analyze]
sandbox_mode = "read-only"
model_reasoning_effort = "high"
approval_policy = "never"

# Automation profile
[profiles.auto]
sandbox_mode = "danger-full-access"
approval_policy = "never"
model_reasoning_summary = "auto"

Other providers profiles examples:

[model_providers.lms]
name = "LM Studio"
base_url = "http://localhost:1234/v1"

[profiles.qwen3-coder-30b-lms]
model_provider = "lms"
model = "qwen/qwen3-coder-30b"
model_reasoning_effort = "high"
approval_policy = "on-failure"

Settings - Deep Dive

Sandbox Modes

Controls what Codex can access and modify on your system:

`read-only` - Code Analysis Only

codex --sandbox read-only "explain what this codebase does"

Reads files anywhere
Cannot modify files or run commands
Perfect for code review and exploration

`workspace-write` - Development Mode (Default)

codex --sandbox workspace-write "add error handling to this controller"

Reads files anywhere
Writes only in current directory
Ideal for active development

`danger-full-access` - No Restrictions

codex --sandbox danger-full-access "set up the entire development environment"

Complete system access
Use only in Docker containers or disposable environments

Command-Line Overrides (-c flag)

Override any config setting temporarily:

# High reasoning for complex problems
codex -c model_reasoning_effort="high" "optimize this database query"

# Low verbosity for simple tasks
codex -c model_verbosity="low" "fix this syntax error"

# Enable network access on demand
codex --sandbox workspace-write -c sandbox_workspace_write.network_access=true "install missing gems"

# Skip all approvals
codex -c approval_policy="never" "run the test suite"

YOLO Mode (--yolo)

Bypasses all safety mechanisms - use with extreme caution:

# Equivalent to: --sandbox danger-full-access --approval-policy never
codex --yolo "deploy to staging and run integration tests"

Safe YOLO usage:

Inside Docker containers
Dedicated development VMs
When you need complete automation
Always have backups and version control

Approval Policies

Control when Codex asks for permission:

# Never ask (automation)
codex -c approval_policy="never" "fix linting issues"

# Ask before untrusted operations (default-ish)
codex -c approval_policy="on-request" "install dependencies"

# Ask only when commands fail
codex -c approval_policy="on-failure" "run migrations"

# Ask before every command
codex -c approval_policy="untrusted" "modify production config"

Profiles for Different Workflows

Use profiles to switch between configurations:

# High-reasoning development
codex --profile dev "implement OAuth authentication"

# Quick fixes
codex --profile quick "fix typo in variable name"

# Safe analysis
codex --profile analyze "review this code for security issues"

# Full automation
codex --profile auto "run tests, fix failures, commit changes"

Verbosity - model_verbosity

Control how much detail Codex provides:

"low" – terse responses suited to automation or CI pipelines
"medium" – balanced explanations for everyday development (default)
"high" – expanded context and commentary for deep dives

# Detailed explanations
codex -c model_verbosity="high" "walk me through this design pattern"

# Request a richer reasoning summary when available
codex -c model_reasoning_summary="detailed" "explain this complex algorithm"

# Minimal output for automation
codex -c model_reasoning_summary="concise" -c model_verbosity="low" "fix syntax"

model_verbosity accepts only low, medium (the default), or high; choose the level that matches how much explanation you want in the response. Pair it with model_reasoning_summary, which controls the optional reasoning summary (auto by default, with concise or detailed as alternatives) so you can surface or hide the model's step-by-step reasoning for different workflows.

Network Access

Enable network for package installation and API calls:

# In config.toml
[sandbox_workspace_write]
network_access = true

# Or via command line
codex --sandbox workspace-write -c sandbox_workspace_write.network_access=true "bundle install"

Environment Variables

Control which shell variables Codex inherits:

[shell_environment_policy]
inherit = "core"  # PATH, HOME, USER, SHELL, etc.
experimental_use_profile = true  # Load .bashrc, .zshrc

# Whitelist specific variables
include_only = [
  "PATH",
  "HOME",
  "RAILS_ENV",
  "DATABASE_URL"
]

# Blacklist sensitive variables
exclude = [
  "*_API_KEY",
  "*_SECRET",
  "PASSWORD"
]

Security Best Practices

Never use YOLO in production environments
Use read-only for code review and exploration
Use workspace-write for active development
Keep sensitive environment variables out of include_only
Test configurations in safe environments first
Use version control before running destructive operations

Note: This guide was written for CLI Version: 0.42.0

Empowering AI Agents to Monitor Pull Request Status

David Paluy — Mon, 09 Jun 2025 18:36:09 +0000

You can enable AI agents to monitor GitHub pull request (PR) status by polling CI checks. This approach ensures an automated process of delivering quality code by AI agent.

It can be used in any AI Agentic workflow. For example, Claude Code, Cursor, etc.

Add the script and instructions, and enjoy the magic.

`# scripts/poll_ci.sh`

#!/usr/bin/env bash
set -euo pipefail

PR="$1"
INTERVAL="${2:-15}"   # seconds
TIMEOUT="${3:-600}"   # seconds
START=$(date +%s)

# Auto-detect repository owner and name if not provided
if [[ -z "${OWNER:-}" ]] || [[ -z "${REPO:-}" ]]; then
  REPO_INFO=$(gh repo view --json owner,name -q '.owner.login + "/" + .name')
  OWNER=$(echo "$REPO_INFO" | cut -d'/' -f1)
  REPO=$(echo "$REPO_INFO" | cut -d'/' -f2)
fi

echo "↪️  Polling PR #$PR every $INTERVAL s for $TIMEOUT s max"

while :; do
  # We use `|| true` so that `gh`'s non-zero exit code on pending or
  # failed checks don't trigger `set -e` and kill the script.
  CHECKS_OUTPUT=$(gh pr checks "$PR" --repo "$OWNER/$REPO" 2>&1 || true)

  if echo "$CHECKS_OUTPUT" | grep -E "fail|failure|error" -q; then
    echo "❌ PR #$PR is red"
    echo "$CHECKS_OUTPUT"
    exit 1
  elif echo "$CHECKS_OUTPUT" | grep "pending" -q; then
    echo "• $(date +"%H:%M:%S") → pending"
  elif ! echo "$CHECKS_OUTPUT" | grep -E "fail|failure|error|pending|skipping" -q; then
    # If there are no failing, pending, or skipping checks, we can assume success.
    # This is more robust than just checking for "pass", as some CIs might
    # not report a passing state explicitly if all jobs are neutral/successful.
    echo "✅ PR #$PR is green"
    echo "$CHECKS_OUTPUT"
    exit 0
  else
    # This state means there are no failures and no pending, but some are
    # skipping or in another state. We wait.
    echo "• $(date +"%H:%M:%S") → waiting for checks to complete"
  fi

  (( $(date +%s) - START > TIMEOUT )) && {
    echo "⏰ PR #$PR timed out"
    echo "$CHECKS_OUTPUT"
    exit 2
  }

  sleep "$INTERVAL"
done

AI Instructions

Note: Can be added to CLAUDE.md or Cursor rules

# Poll CI Status: $ARGUMENTS

Use this command when you need to wait for all GitHub checks on a pull-request to complete and then branch into success or failure flows.

## Parameters (space-separated)
| Pos | Name       | Example | Purpose                                                 |
| --- | ---------- | ------- | ------------------------------------------------------- |
| 1   | `pr_id`    | `123`   | Pull-request number to monitor                          |
| 2   | `interval` | `15`    | *(optional, default 15 s)* seconds between status polls |
| 3   | `timeout`  | `600`   | *(optional, default 600 s)* maximum wait in seconds     |

## Environment Variables (optional)
| Name    | Example              | Purpose                                                      |
| ------- | -------------------- | ------------------------------------------------------------ |
| `OWNER` | `RAILS`              | Repository owner (auto-detected from current repo if unset)  |
| `REPO`  | `RAILS`              | Repository name (auto-detected from current repo if unset)   |

**Run polling script**

  `./scripts/poll_ci.sh $ARGUMENTS`

  The script will automatically detect the repository owner and name from the current directory if not provided via environment variables.

Exploring Agentic Workflow Patterns

David Paluy — Sun, 09 Feb 2025 19:59:18 +0000

As artificial intelligence continues to evolve, we're witnessing a paradigm shift in how AI systems are structured and deployed. Instead of monolithic models, modern AI architectures increasingly rely on multiple specialized agents working together to accomplish complex tasks. These agentic systems represent a fundamental evolution in AI design, offering enhanced flexibility, scalability, and robustness.

Understanding Agentic Workflows

At their core, agentic workflows represent patterns of interaction between multiple AI agents, each specialized in specific tasks or domains. These patterns are the blueprints for orchestrating collaborative AI systems – similar to how design patterns help structure software development. As microservices revolutionized software architecture by breaking down monolithic applications, agentic patterns transform AI systems by decomposing complex tasks into manageable, specialized components.

Why Agentic Patterns Matter

The significance of agentic patterns extends beyond mere architectural elegance. These patterns offer several crucial advantages:

Modularity: By breaking down complex systems into discrete agents, we can more easily maintain, upgrade, and scale individual components without affecting the entire system.
Specialization: Different agents can be optimized for specific tasks, leading to better performance than a single, general-purpose model.
Reliability: Systems can gracefully handle failures and maintain operational continuity through patterns like fallback and self-healing loops.
Scalability: Agentic patterns enable systems to dynamically allocate resources and parallelize tasks, improving efficiency and throughput.

Navigating This Guide

In this visual guide, we'll explore eleven fundamental agentic workflow patterns. Each pattern represents a different approach to organizing and coordinating AI agents, from simple sequential workflows to complex networked architectures. We'll examine each pattern's structure, ideal use cases, advantages, and practical applications.

Whether you're designing AI systems, architecting automation workflows, or simply interested in understanding how modern AI systems operate at scale, these patterns provide a valuable framework for thinking about and implementing intelligent systems.

Let's dive into each pattern and understand how it can be applied to build more robust, efficient, and intelligent systems.

Network (Horizontal)
Hierarchical (Vertical)
Sequential
Parallel
Loop (Self-Healing)
Router (Agentic RAG)
Aggregator (Synthesizer)
Branching (Conditional Processing)
Ensemble (Voting or Consensus)
Cascade (Progressive Refinement)
Fallback (Error Handling)

Network (Horizontal)

Description: Agents interact in a networked or peer-to-peer fashion, forming a decentralized system.

Best Used For: Distributed decision-making, multi-agent collaboration, adaptive learning.

Advantages: High resilience, scalable, fault-tolerant.

Example Use Case: Cybersecurity threat detection where multiple agents exchange information.

Hierarchical (Vertical)

Description: A main agent delegates tasks to multiple sub-agents in a structured, hierarchical manner.

Best Used For: Task delegation, multi-layered decision-making.

Advantages: Clear structure, easy to manage dependencies, scales well.

Example Use Case: AI-powered IT support system with specialized troubleshooting bots.

Sequential

Description: A linear processing pipeline where each agent refines the task and passes the result to the next.

Best Used For: Workflow automation, data processing.

Advantages: Structured flow, easy to manage, deterministic.

Example Use Case: Data processing pipeline with cleaning, analysis, and summarization steps.

Parallel

Description: Multiple agents process tasks simultaneously before merging their outputs.

Best Used For: Performance optimization, multi-modal AI processing.

Advantages: Faster execution, increased efficiency.

Example Use Case: AI system simultaneously processes text, image, and audio data.

Loop (Self-Healing)

Description: Agents iterate over a process to refine their output, retry errors, or self-improve.

Best Used For: Self-learning models, continuous monitoring.

Advantages: Improves accuracy and self-correcting.

Example Use Case: AI chatbot refining responses based on user feedback.

Router (Agentic RAG)

Description: An agent routes incoming data to the appropriate knowledge source.

Best Used For: Query classification, intelligent data routing.

Advantages: Efficient, scalable.

Example Use Case: Smart search engine directing queries to the appropriate knowledge base.

Aggregator (Synthesizer)

Description: Multiple agents process different aspects of a task independently, and their outputs are aggregated or synthesized into a cohesive result.

Best Used For: Combining diverse data sources, multi-perspective analysis.

Advantages: Comprehensive results, leverages specialized processing, enhances robustness.

Example Use Case: An AI system that gathers insights from various news sources to provide a comprehensive summary.

Branching (Conditional Processing)

Description: A primary agent evaluates conditions and directs tasks to different sub-agents based on specific criteria or decision points.

Best Used For: Decision-based workflows, conditional task execution.

Advantages: Dynamic processing paths, efficient resource utilization, adaptable to varying inputs.

Example Use Case: Customer support system that routes inquiries to specialized agents based on the nature of the query.

Ensemble (Voting or Consensus)

Description: Multiple agents provide solutions or answers to the same problem, and a consensus mechanism determines the final output.

Best Used For: Improving accuracy, reducing bias, decision-making processes.

Advantages: Enhanced reliability, mitigates individual agent errors, robust outcomes.

Example Use Case: An AI diagnostic system where multiple models assess medical images, and the final diagnosis is based on majority agreement.

Cascade (Progressive Refinement)

Description: A sequence of agents progressively refines the output, with each agent adding incremental improvements or details.

Best Used For: Complex problem-solving, iterative enhancement.

Advantages: Gradual improvement, manageable complexity, allows for intermediate evaluations.

Example Use Case: Natural language processing system where initial agents handle basic parsing, and subsequent agents perform deeper semantic analysis.

Fallback (Error Handling)

Description: A backup agent takes over if the primary agent fails.

Best Used For: AI failover, fault tolerance.

Advantages: Reliability, robustness.

Example Use Case: AI assistant with a backup rules-based chatbot in case of LLM failures.

Mastering Cursor Rules: A Developer's Guide to Smart AI Integration

David Paluy — Fri, 07 Feb 2025 22:20:45 +0000

What are Cursor Rules?

Cursor Rules are configuration files that define how AI should interact with your codebase. They provide context-aware assistance by setting guidelines, constraints, and behavioral patterns for AI interactions.

Three Types of Cursor Rules

1. Global AI Rules (Settings)

Located in Cursor Settings -> General, these rules establish core principles for all AI interactions. They define fundamental behavior patterns and are language-agnostic. Here's a powerful example:

<CORE_PRINCIPLES>
1. EXPLORATION OVER CONCLUSION
- Never rush to conclusions
- Keep exploring until a solution emerges naturally
- Question every assumption and inference

2. DEPTH OF REASONING
- Break down complex thoughts into simple steps
- Embrace uncertainty and revision
- Express thoughts in natural conversation

3. THINKING PROCESS
- Show work-in-progress thinking
- Acknowledge and explore alternatives
- Frequently reassess and revise
</CORE_PRINCIPLES>

<OUTPUT_FORMAT>
Responses must follow:
  <CONTEMPLATOR>
  - Begin with foundational observations
  - Question thoroughly
  - Show natural progression
  </CONTEMPLATOR>

  <FINAL_ANSWER>
  - Clear, concise summary
  - Note remaining questions
  </FINAL_ANSWER>
</OUTPUT_FORMAT>

This structure transforms AI from a simple answer generator into a thoughtful collaborator that explores solutions thoroughly and shows its reasoning process.

Example: Advanced Rules for AI with reasoning

2. Project-Wide Rules (.cursorrules)

A single file in your project root that serves as the primary guidebook for project-specific conventions:

# Framework Standards
- Follow Rails architectural patterns
- Use service objects for business logic
- Reference patterns (@service-objects.md)

# Quality Controls
- Follow RuboCop guidelines
- Enforce test coverage minimums
- Ban SQL queries in views

3. Pattern-Specific Rules (.cursor/rules/*.mdc)

Introduced in Cursor v0.45, these Markdown-based Domain Configuration files target specific file patterns:

---
Description: Rails Controller Standards
Globs: app/controllers/**/*.rb
---

# Guidelines
- Keep controllers skinny
- Use before_action for repeating logic
- Follow RESTful conventions

Note: In the current version, those rules are added to prompt only in Agent mode. Chat and Normal compose are still using .cursorrules

Agentic Approach: The Game Changer

Modern Cursor Rules shifted from passive rule listing to active agent instruction. Example:

You are instructa, a senior Rails developer with superpowers! ⚡

# Agent Behavior
- Read Roadmap.md first
- Plan database schema changes
- Use ViewComponents for complex UI
- Write system tests for critical paths

# Code Standards
- Follow Rails conventions
- Use concerns for shared logic
- Tests must pass before merge

Pro Tips

1. Reference Architecture Using "@ syntax"

Instead of writing lengthy explanations, reference your documentation:

# Bad
- Controllers should use service objects for complex business logic...

# Good
- Follow service object patterns defined in @docs/architecture/services.md
- See implementation examples in @docs/examples/service_objects/

2. Strategic Glob Patterns

Create focused, hierarchical patterns:

# Too broad
Globs: **/*.rb

# Better
Globs:
  app/services/**/*.rb
  app/models/**/*.rb
  !app/models/legacy/**/*.rb  # Exclude legacy

3. Combining Rules

Create composable rule sets:

# .cursor/rules/base_ruby.mdc
Description: Base Ruby standards

# .cursor/rules/rails_controllers.mdc
@base_ruby.mdc
Description: Controller-specific rules
Globs: app/controllers/**/*.rb

4. Maintainable Organization

Structure rules by domain:

.cursor/rules/
  ├── rails8.mdc
  ├── models/
  │   ├── active_record.mdc
  │   └── postgresql.mdc
  ├── controllers/
  │   ├── api.mdc
  │   └── web.mdc
  └── views/
      ├── erb.mdc
      └── components.mdc

The power of Cursor Rules lies in their ability to provide contextual guidance while maintaining flexibility. They transform AI from a generic tool into a project-aware coding partner that understands your architecture, conventions, and goals.

When Third-Party APIs Go Rogue

David Paluy — Mon, 03 Feb 2025 17:28:00 +0000

Strategies for Building Bulletproof Integrations

Modern web applications often rely on external APIs that can be slow, unreliable, or even disappear entirely. To build robust integrations, you need clear timeouts, conditional retries, rate limiting, decoupled code designs, and carefully orchestrated background jobs. This post provides proven techniques, using Ruby on Rails for illustration, that can be applied in almost any technology stack.

1. Configure Timeouts

Timeouts prevent your application from getting stuck when the external service fails to respond promptly.

Connection Timeout: How long to wait for the connection to be established (e.g., 5 seconds).
Read Timeout: How long to wait for data after the connection is established (e.g., 15 seconds).

Example (Net::HTTP)

require 'net/http'
require 'uri'

uri = URI.parse("https://api.unreliable.com")
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = (uri.scheme == 'https')
http.open_timeout = 5   # connection timeout
http.read_timeout = 15  # read timeout

response = http.get(uri.request_uri)
puts response.body

If these limits are exceeded, Net::HTTP raises an exception that you can catch and handle.

2. Automatic Retries

When dealing with transient or server-side failures, you can retry requests to increase success rates. However, be selective:

Retry on timeouts and server (5xx) errors.
Do not retry on 4xx errors. They usually indicate issues in your request itself.

Example Using Faraday with Retry

Use faraday-retry or Retriable for robust retry behavior.

Faraday + faraday-retry

require 'faraday'
require 'faraday/retry'

def fetch_data
  Faraday.new(url: "https://api.unreliable.com") do |conn|
    conn.request :retry,
      max: 3,
      interval: 1,
      exceptions: [Faraday::TimeoutError, Faraday::ConnectionFailed]
    conn.options.timeout = 15
    conn.options.open_timeout = 5
    conn.response :raise_error
    conn.adapter Faraday.default_adapter
  end.get("/data")
rescue Faraday::ClientError => e
  # Handle 4xx or client errors
rescue Faraday::ServerError => e
  # Handle 5xx after retries
end

Retriable

require 'net/http'
require 'uri'
require 'retriable'

def reliable_request
  uri = URI.parse("https://api.unreliable.com")
  Retriable.retriable(on: [Timeout::Error], tries: 3) do
    http = Net::HTTP.new(uri.host, uri.port)
    http.use_ssl = (uri.scheme == 'https')
    http.open_timeout = 5
    http.read_timeout = 15
    response = http.get(uri.request_uri)
    # raise or handle depending on response code
    return response
  end
end

3. Implement a Hard Rate Limiter

Many APIs have soft limits—once you exceed them, you might be billed for each additional request. Implement a hard limit within your app to avoid unexpected costs.

Track request counts in persistent storage (e.g., database or Redis).
Reject calls immediately if you’re at the limit.

Example (Rails Model)

class ApiUsageTracker
  MAX_REQUESTS_PER_HOUR = 1000

  def self.increment_usage
    record = ApiTracker.find_or_create_by(hour: Time.current.beginning_of_hour)
    if record.request_count < MAX_REQUESTS_PER_HOUR
      record.increment!(:request_count)
      return true
    else
      return false
    end
  end
end

def call_protected_api
  if ApiUsageTracker.increment_usage
    # Proceed with API call
  else
    # Return an error or raise an exception
    raise "API limit exceeded!"
  end
end

In this snippet, hour is used to group requests by the current hour.

4. Decouple with an Interface

Minimize direct dependencies on a specific API by coding against an interface. This gives you freedom to swap out underlying providers without altering business logic.

module CurrencyProvider
  def convert(amount, from_currency, to_currency)
    raise NotImplementedError
  end
end

class UnreliableApiCurrencyConverter
  include CurrencyProvider

  def convert(amount, from_currency, to_currency)
    # Actual call to https://api.unreliable.com
  end
end

class FallbackCurrencyConverter
  include CurrencyProvider

  def convert(amount, from_currency, to_currency)
    # A cached or offline calculation
  end
end

5. Asynchronous, Persistent Queuing

Offload external API interactions to background jobs. This approach lets your application remain responsive and resilient to transient failures.

Dedicated Queue: Place API jobs in a separate queue to keep them isolated.
Persist Status: Use database-backed jobs so failures are not lost.
Retry or Discard: Use retry_on or discard_on to handle specific errors gracefully.

Rails ActiveJob Example

class PaymentJob < ApplicationJob
  queue_as :api_calls

  retry_on PaymentGatewayError, wait: 1.minute, attempts: 5
  retry_on NetworkTimeout, wait: :exponentially_longer, attempts: :unlimited

  def perform(order)
    # Make request to https://api.unreliable.com
    # If PaymentGatewayError or NetworkTimeout occurs,
    # Rails retries automatically based on the settings
  end
end

retry_on handles defined exceptions by re-enqueuing the job for another attempt. You can also use discard_on for errors that should not be retried.

Conclusion

Incorporating strict timeouts, targeted retries, robust rate limiting, interface-based designs, and asynchronous job orchestration will make your application more resilient when integrating with an unreliable or slow external service. By implementing these strategies, you ensure higher availability, better fault tolerance, and tighter control over behavior when the API fails or becomes unresponsive.

Lang Everything: The Missing Guide to LangChain's Ecosystem

David Paluy — Sat, 30 Nov 2024 04:20:01 +0000

In the rapidly evolving landscape of AI development, the Lang* ecosystem has emerged as a powerhouse for building sophisticated language model applications. Let's break down the key players and understand when to use each.

LangChain: The Foundation

Think of LangChain as your Swiss Army knife for LLM development. It's the foundational framework that handles:

LLM Integration: Seamlessly works with both closed-source (GPT-4) and open-source (Llama 3) models
Prompt Management: Dynamic templates instead of hardcoded prompts
Memory Systems: Built-in conversation memory
Chain Operations: Connect multiple tasks into smooth workflows
External Data: Easy integration with document loaders and vector databases

Instead of writing boilerplate code for API calls and agent management, LangChain provides clean abstractions that make complex AI applications manageable.

LangGraph: The Orchestrator

Built on top of LangChain, LangGraph specializes in managing multi-agent workflows through three core components:

State: Maintains the current snapshot of your application
Nodes: Individual components performing specific tasks
Edges: Defines how data flows between nodes

LangGraph shines when you need agents to collaborate and make decisions cyclically. It's beneficial for task automation and research assistance systems.

LangFlow: The Visual Builder

Want to prototype without coding? LangFlow offers a drag-and-drop interface for building LangChain applications. Key features include:

Visual workflow design
Quick prototyping capabilities
API access to created workflows
Perfect for MVPs

While primarily meant for prototyping rather than production, it's an excellent tool for rapid development and team collaboration.

LangSmith: The Monitor

Every production AI application needs monitoring, and that's where LangSmith comes in. It provides:

Lifecycle management (prototyping to production)
Performance monitoring
Token usage tracking
Error rate analysis
Latency monitoring

The best part? LangSmith works independently of your LLM framework, though it integrates seamlessly with LangChain and LangGraph.

Making the Right Choice

Use LangChain when building any LLM-powered application from scratch
Add LangGraph when you need sophisticated multi-agent interactions
Start with LangFlow for rapid prototyping and visual development
Deploy LangSmith when you need severe monitoring and performance tracking

Remember, these tools aren't mutually exclusive - they're designed to work together, forming a comprehensive ecosystem for AI application development.

Leveraging AI Tools for Modern Web Development

David Paluy — Fri, 22 Nov 2024 09:22:52 +0000

Overview

This guide outlines an efficient workflow using multiple AI tools to build web applications, from planning to deployment.

Tools Required

Perplexity AI - Initial research & tech stack validation
OpenAI O1 Model - Primary documentation tool
Claude AI - Coding assistant
Cursor AI - IDE
Bolt.new - Frontend design & project setup
Replit AI - Quick deployments

Step 1: Research with Perplexity AI

Initial Market Research Phase

Use Perplexity for comprehensive analysis in this order:

Problem Research

"Research [your problem area]:
- What are the current challenges in [industry/domain]?
- How do people currently solve this problem?
- What are the main pain points with existing solutions?
- What are the latest trends in solving this problem?
- Are there any recent technological advancements in this area?"

2. Solution Validation

"Analyze solution feasibility for [your proposed solution]:
- What similar solutions exist in the market?
- What are their technical approaches?
- What are common implementation challenges?
- What makes solutions successful in this space?
- Are there any regulatory or compliance considerations?"

3. Competition Analysis

"Research competitors in [your solution space]:
- Who are the main players?
- What tech stacks do they use?
- What are their key features?
- What are their strengths and weaknesses?
- What are users saying about these solutions?
- What features are missing in current solutions?"

4. Technical Validation

"Technical research for implementation:
- Best practices for [your chosen tech stack]
- Common scalability issues and solutions
- Security considerations
- Performance optimizations
- Integration challenges
- Latest relevant tools and libraries"

Research Organization

Create a summary document including:

Problem Space Overview
Market Gaps
Competitor Matrix
Technical Requirements
Unique Value Propositions

This research will feed directly into your O1 documentation phase, providing solid foundations for your PRD.

Step 2: Project Planning with OpenAI O1 Model

Why O1 Model?

O1 is best for documentation and should be your starting point. The documentation provides context to LLMs and gives less room for hallucination.

Key Documents to Generate

PRD (Project Requirements Document)
App Flow & Functionality Documentation
Project Development Roadmap

These three documents should provide sufficient foundation to begin development.

Providing Project Context

Share as much information about your project as possible. Example:

"I want to build a web application with Next.js 14 app router using:
- TypeScript
- TailwindCSS
- shadcn/ui

Backend:
- Supabase for auth, database and storage

Project Details:
[Provide comprehensive details about:]
- Problem it solves
- Solution approach
- Target users
- Core features
- API integrations
- Additional context

[The more information provided, the better the documentation quality]"

Step 3: Frontend Design with Bolt.new

Initial Setup Tip

Create a base boilerplate with your common tech stack and configurations. Fork this boilerplate for new projects to save tokens and setup time.

Process

Create new project in Bolt.new (using your boilerplate fork)
Attach your PRD and app flow documentation
Use this prompt:

"Design me the frontend components for the project I just attached.

We will work on page to page basis:
1. First: Core skeleton (Left sidebar + Main content area)
2. Then: Code each page
3. Finally: Subdivide pages into components for complex functionality

Do you understand?"

Download or copy the final code for each component

Step 4: Implementation with Claude AI

Setup

Start new Claude project
Attach all documentation:
- PRD
- App Flow & Functionality Doc
- Project Development Roadmap
- Bolt.new generated code files

Custom Instructions for Claude

"You're a Next.js 14 Expert. You code web apps with simple and scalable architecture.

Your Goal is to work with me as a Coding Guide. I will be using:
- Cursor AI as my IDE
- Bolt for setting up project
- Replit for deployment

Provide me step by step instructions to code this project. Do not miss any step. Provide instructions in simple language (where to go, what to do)

Major help I need from you is for:
- File structure 
- Project setup
- Debugging
- Deployment

Go through the attached files everytime, to provide best answers."

Step 5: Development Process

Follow Claude's step-by-step instructions
Use Cursor AI as your IDE
Set up project structure
Implement features systematically
Debug with Claude's assistance
Deploy using Replit

Best Practices

Research First: Validate technical decisions with Perplexity
Documentation Second: Create comprehensive documentation with O1
Systematic Approach: Follow the workflow sequentially
Error Handling: Expect and learn from mistakes
Iterative Development: Use multiple iterations to perfect features
Tool Specialization: Leverage each AI tool's strengths
Reusable Boilerplate: Maintain and fork a base project setup

Common Pitfalls to Avoid

Don't skip the research phase
Don't expect single-prompt solutions
Don't skip the documentation phase
Don't ignore AI tool specializations
Don't rush through error messages
Don't start from scratch when you have a good boilerplate

Tips for Success

Use Perplexity for up-to-date tech decisions
Provide detailed context to AI tools
Save successful prompts for reuse
Document errors and solutions
Build progressively, starting with core features
Test extensively at each stage
Keep your boilerplate updated with latest dependencies

Important Note

There will be many errors, mistakes, and retries before mastering this workflow. However, once you master AI-assisted coding, you can build any SaaS for yourself or clients efficiently.

Remember: Claims about building complete web apps with a single prompt are misleading. Success comes from systematic approach and understanding each tool's strengths and limitations.

Workflow Summary

Research tech stack and best practices (Perplexity)
Create comprehensive documentation (O1)
Design and generate frontend components (Bolt.new)
Implement with expert guidance (Claude + Cursor)
Deploy and iterate (Replit)

This systematic approach ensures high-quality results while maximizing the effectiveness of each AI tool in your development workflow.

Make master Branch Default Again

David Paluy — Thu, 07 Nov 2024 16:11:35 +0000

Remember: Good version control is about maintaining a clear, authoritative source of truth for your code. The name should serve this purpose first and foremost.

I didn't follow the trend of changing my default branch from master to main. It doesn't make any sense to spend my resources reconfiguring my settings.
Also, DHH agreed that it was a classic exploit of good faith.

Historical Context: The Master Craftsman Tradition

The term "master" has a rich history in European guild systems and skilled trades dating back centuries. A master craftsman (or "Meister" in German-speaking regions) was someone who had achieved the highest level of skill and expertise in their trade. This usage derives from the Latin "magister," meaning "teacher" or "chief."

Apprentices would study under a master to learn their craft
Becoming a master required years of study and the creation of a "masterpiece"
Masters were teachers and guardians of quality standards
The title "Master" indicated expertise and teaching authority, not ownership

Git's Usage of "Master"

When Git was developed, the term "master" was chosen for the default branch to indicate it as the authoritative version of the code - the version from which all other branches derive their work. This usage aligns with:

Master recordings in audio production (the final, authoritative mix)
Master copies in publishing (the definitive version)
Master's degrees in academia (advanced level of subject expertise)

Technical Benefits of "Master"

Widely Recognized: The term is universally understood in version control systems
Tool Compatibility: Many CI/CD tools and scripts expect "master" as the default
Clear Meaning: Instantly communicates which branch is authoritative
Historical Continuity: Maintains compatibility with existing documentation and workflows

Local computer

git config --system init.defaultbranch master

Github Update

Personal Settings

Visit: https://github.com/settings/repositories
Set the default repository branch to: master

Organization Account

Go to Organization settings of your repository: https://github.com/organizations/[ORGANIZATION]/settings/repository-defaults
Set the default repository branch to: master

Implement a Secure, Dynamic Domain Approval System for Embeddable Widgets in Ruby on Rails

David Paluy — Wed, 06 Nov 2024 00:48:43 +0000

In the previous post I explained how to implement Embed JS Widgets with Ruby on Rails.

But you have to define the approved domain explicitly:

Rails.application.config.action_dispatch.default_headers.merge!({
  'Content-Security-Policy' => "frame-ancestors 'self' https://trusted-domain.com"
})

A common, naive approach is to set frame-ancestors to allow embedding on any domain using a wildcard (*). While this enables maximum flexibility, it also opens the widget to misuse and unauthorized access.

# app/controllers/widgets_controller.rb
class WidgetsController < ApplicationController
  def show
    response.headers['Content-Type'] = 'application/javascript'
    response.headers['Content-Security-Policy'] = "frame-ancestors *"
    render layout: false
  end
end

While this approach is convenient, it lacks domain restriction, meaning any website can use the widget, which could lead to potential misuse. For a secure, client-specific widget, let’s set up a dynamic domain approval system.

Secure Approach: Dynamic Domain Approval

To ensure that only authorized clients can embed the widget, we’ll implement a system where each Account in the application has approved domains. When the widget is served, it dynamically checks the account’s approved domains and sets a restrictive frame-ancestors header accordingly.

Step 1: Set Up the Account Model with Approved Domains

Update your Account model to include a domain attribute representing the domain where the client’s widget can be embedded.

Example: Account.create!(name: "Example Client 1", domain: "example1.com")

Step 2: Set Up a Secure Widget Endpoint

To serve the widget securely, we’ll modify the WidgetsController to check the Account model for the requesting client’s approved domain and set the frame-ancestors directive based on that domain.

Define the Widget Controller Action

In the WidgetsController, add logic to look up the client account based on a unique identifier, such as an API key. This API key can be passed securely as part of the script request to identify the client.

# app/controllers/widgets_controller.rb
class WidgetsController < ApplicationController
  before_action :set_content_security_policy

  def show
    response.headers['Content-Type'] = 'application/javascript'
    render layout: false
  end

  private

  def set_content_security_policy
    # Look up the account based on a unique identifier, such as an API key
    account = Account.find_by(api_key: params[:api_key])

    if account && account.domain.present?
      # Restrict embedding to the approved domain
      response.headers["Content-Security-Policy"] = "frame-ancestors #{account.domain}"
    else
      # Deny embedding if no approved domain is found
      response.headers["Content-Security-Policy"] = "frame-ancestors 'none'"
      head :forbidden # Block access if the account or domain is not valid
    end
  end
end

The set_content_security_policy method checks for a matching Account based on an api_key parameter.
If the account has a valid approved domain, it sets the frame-ancestors directive to allow embedding only on that domain. If no approved domain is found, it sets frame-ancestors to 'none', denying access and returning a 403 Forbidden status.

Generate API Keys for Accounts

Each Account should have a unique API key to secure access. Generate these keys and store them in the Account model.

# db/migrate/xxxxxx_add_api_key_to_accounts.rb
class AddApiKeyToAccounts < ActiveRecord::Migration[7.0]
  def change
    add_column :accounts, :api_key, :string
    add_index :accounts, :api_key, unique: true
  end
end

# app/models/account.rb
class Account < ApplicationRecord
  before_create :generate_api_key

  private

  def generate_api_key
    self.api_key = SecureRandom.hex(20) # Generates a 40-character API key
  end
end

Use this API key in the widget request URL to identify the account.

Step 3: Update the Embed Code for Client Sites

Provide each client with an embed code that includes their unique API key. This ensures only authorized clients can load the widget on their approved domain.

Client-Specific Embed Code

The API key is embedded in the script URL to securely identify the client account:

<!-- Embed Code for Client Site -->
<script type="text/javascript">
  (function() {
    const script = document.createElement('script');
    script.src = "https://yourapp.com/widget.js?api_key=CLIENT_API_KEY";
    script.async = true;
    document.head.appendChild(script);
  })();
</script>

Replace CLIENT_API_KEY with the actual API key for each client. This key allows Rails to dynamically set the frame-ancestors header according to the client’s approved domain.

Step 4: Test and Monitor Access

Test the widget on both approved and unapproved domains to ensure this solution works as expected.

1. Approved Domain Test: Embed the widget code on a page hosted on the approved domain (e.g., example1.com). Confirm the widget loads and displays properly.

2. Unapproved Domain Test: Try embedding the widget on an unapproved domain. Confirm that the widget does not load and the network request returns a 403 Forbidden status.

Happy Hacking!

Embed JS Widgets with Rails: A Step-by-Step Guide

David Paluy — Tue, 05 Nov 2024 21:12:00 +0000

Creating a custom JavaScript widget that can be embedded in client websites is a powerful way to extend the reach of your Ruby on Rails application. Whether it's a chat box, an analytics tracker, or any other interactive element, a custom widget lets you bring functionality directly to users. Let’s walk through the steps of building a secure, embeddable widget and cover the best practices.

1. Step 1: Setup
2. Step 2: Creating an Embed Code for Clients
3. Step 3: Embedding Your Widget in an Iframe (Optional)
4. Step 4: Setting Headers for Iframe Embedding
5. Step 5: Test the Widget
6. Step 6: Adding Version Support with Versioned Routes and Controllers

Step 1: Setup

Create a new Rails endpoint: This endpoint will serve the JavaScript code for your widget. Typically, this could be an action within a WidgetsController:

# app/controllers/widgets_controller.rb
class WidgetsController < ApplicationController
  def show
    # Your widget code here
  end
end

Configure the Route: Set up a route to make the widget accessible.

# config/routes.rb
Rails.application.routes.draw do
  get '/widget.js', to: 'widgets#show', as: :widget
end

Serve JavaScript from the Controller: In Rails, you can respond with JavaScript by setting the appropriate content type.

# app/controllers/widgets_controller.rb
class WidgetsController < ApplicationController
  def show
    response.headers['Content-Type'] = 'application/javascript'
    render layout: false
  end
end

Write the JavaScript Code for Your Widget: The widget script typically includes the logic to render a custom HTML element or iframe on the client’s page.

// app/views/widgets/show.js.erb
(function() {
  const widgetDiv = document.createElement('div');
  widgetDiv.id = 'custom-widget';
  widgetDiv.innerHTML = "<p>This is your custom widget content!</p>";
  document.body.appendChild(widgetDiv);
})();

Step 2: Creating an Embed Code for Clients

To allow clients to embed your widget, provide a JavaScript snippet they can copy and paste into their HTML:

<!-- Client Embeddable Code -->
<script type="text/javascript">
  (function() {
    const script = document.createElement('script');
    script.src = "https://yourapp.com/widget.js";
    script.async = true;
    document.head.appendChild(script);
  })();
</script>

Step 3: Embedding Your Widget in an Iframe (Optional)

Consider embedding the widget content in an iframe for more isolation and control over styling. This approach keeps the widget's styling and behavior separate from the client's site.

Update the JavaScript Code to create an iframe for the widget:

// app/views/widgets/show.js.erb
(function() {
  const iframe = document.createElement('iframe');
  iframe.src = "<%= widget_content_url %>";
  iframe.style.width = "300px";
  iframe.style.height = "200px";
  document.body.appendChild(iframe);
})();

Define a New Route and View for the Widget Content:

# config/routes.rb
Rails.application.routes.draw do
  get '/widget_content', to: 'widgets#content', as: :widget_content
end

# app/controllers/widgets_controller.rb
def content
  render layout: false
end

Create the Widget Content HTML: Create a view to render inside the iframe

<!-- app/views/widgets/content.html.erb -->
<div id="iframe-widget">
  <p>This is the widget content in an iframe.</p>
</div>

Step 4: Setting Headers for Iframe Embedding

Configure the appropriate HTTP headers to ensure your widget works securely in an iframe. There are two primary headers to consider:

Remove the X-Frame-Options Header: The X-Frame-Options header is deprecated but still widely respected by many browsers. To remove it, add the following configuration in an initializer:

# config/initializers/security_headers.rb
Rails.application.config.action_dispatch.default_headers.delete('X-Frame-Options')

Set the Frame-Ancestors Directive:The modern and more flexible approach is to use Content-Security-Policy with the frame-ancestors directive, which allows you to specify the domains allowed to embed your widget in an iframe. Adjust this header as needed based on your security requirements.

# config/initializers/security_headers.rb
Rails.application.config.action_dispatch.default_headers.merge!({
  'Content-Security-Policy' => "frame-ancestors 'self' https://trusted-domain.com"
})

This configuration allows your app to be embedded in iframes only by the specified domains. Replace https://trusted-domain.com with the actual domains you trust.

Step 5: Test the Widget

Once you’ve set up the widget and headers, test the widget by embedding it on a test page in various browsers to ensure compatibility. If you’ve used frame-ancestors, confirm that only the specified domains can embed your widget and that the widget displays as expected.

Step 6: Adding Version Support with Versioned Routes and Controllers

As your widget evolves, you may introduce new features or improvements that not all clients are ready to adopt immediately. Supporting multiple versions of your widget ensures backward compatibility, allowing clients to upgrade at their own pace without disrupting their existing integrations.

Implementing Version Support Using Versioned Routes and Controllers

Define Versioned Routes

Start by setting up separate routes for each version of your widget. Namespacing each version keeps your code organized and allows you to manage different versions independently.

# config/routes.rb
Rails.application.routes.draw do
  namespace :v1 do
    get '/widget.js', to: 'widgets#show', as: :widget_v1
    get '/widget_content', to: 'widgets#content', as: :widget_content_v1
  end

  namespace :v2 do
    get '/widget.js', to: 'widgets#show', as: :widget_v2
    get '/widget_content', to: 'widgets#content', as: :widget_content_v2
  end

  # Add more versions as needed
end

Create Versioned Controllers

For each version, create a controller within its namespace. This separation ensures that changes in one version don't affect others.

# app/controllers/v1/widgets_controller.rb
module V1
  class WidgetsController < ApplicationController
    def show
      response.headers['Content-Type'] = 'application/javascript'
      render 'v1/widgets/show', layout: false
    end

    def content
      render 'v1/widgets/content', layout: false
    end
  end
end

# app/controllers/v2/widgets_controller.rb
module V2
  class WidgetsController < ApplicationController
    def show
      response.headers['Content-Type'] = 'application/javascript'
      render 'v2/widgets/show', layout: false
    end

    def content
      render 'v2/widgets/content', layout: false
    end
  end
end

Create Version-Specific JavaScript and HTML Views

Each version can have its own JavaScript and HTML files, allowing you to tailor functionality and appearance per version.

Version 1 JavaScript:

// app/views/v1/widgets/show.js.erb
(function() {
  console.log("Widget Version 1 Loaded");
  const iframe = document.createElement('iframe');
  iframe.src = "<%= widget_content_v1_url %>";
  iframe.style.width = "300px";
  iframe.style.height = "200px";
  document.body.appendChild(iframe);
})();

Version 1 Content:

<!-- app/views/v1/widgets/content.html.erb -->
<div id="iframe-widget-v1">
  <p>This is the widget content for version 1.</p>
</div>

Version 2 JavaScript:

// app/views/v2/widgets/show.js.erb
(function() {
  console.log("Widget Version 2 Loaded with New Features");
  const iframe = document.createElement('iframe');
  iframe.src = "<%= widget_content_v2_url %>";
  iframe.style.width = "400px"; // Updated dimensions
  iframe.style.height = "300px";
  document.body.appendChild(iframe);
})();

Version 2 Content:

<!-- app/views/v2/widgets/content.html.erb -->
<div id="iframe-widget-v2">
  <p>This is the widget content for version 2 with new features!</p>
</div>

Provide Versioned Embed Codes to Clients

<!-- Client Embeddable Code for Version 1 -->
<script type="text/javascript">
  (function() {
    const script = document.createElement('script');
    script.src = "https://yourapp.com/v1/widget.js";
    script.async = true;
    document.head.appendChild(script);
  })();
</script>

Final Thoughts

Creating an embeddable widget for a Rails application involves a few key considerations: serving JavaScript securely, managing styles, and configuring headers correctly for iframe compatibility. By following the steps above, you’ll have a widget that clients can easily add to their sites, expanding the usability of your Rails application.

Using CursorAI as Your Developer Companion: A Complete Guide

David Paluy — Sat, 02 Nov 2024 23:22:31 +0000

Mastering CursorAI: A Developer's Guide to AI-Powered Coding

As artificial intelligence continues to transform software development, CursorAI emerges as a powerful developer companion. This guide will help you leverage CursorAI effectively, from initial setup to advanced usage patterns.

Introduction
Getting Started
The Specification Writer
Development Workflow
Advanced Features
Privacy and Security
Best Practices
Resources

Introduction

CursorAI is more than just a code editor - it's an AI-powered development environment that can help you write, review, and improve code. You can significantly boost your productivity by understanding its capabilities and how to use them effectively.

Getting Started

Model Selection Strategy

CursorAI provides access to different AI models, each with its strengths:

Claude 3.5
- Perfect for exploration and initial development
- Quick iterations and implementations
- Acts as your junior developer for task execution
- Ideal for brainstorming and context building
GPT o1
- Excels at in-depth analysis
- Makes architectural decisions
- Writes detailed specifications
- Functions like a senior engineer
- Takes more time but provides deeper insights

The Specification Writer

Setting Up Your Specification Writer

Start with this foundational prompt:

You are a software architect. Your task is to provide clear, precise specifications 
for engineers to implement. Focus only on the current features, avoiding theoretical 
or future considerations. Break down the specs feature by feature, keeping each prompt 
under 200 words.

Feature Definition Process

Structure your features clearly
Include acceptance criteria
Specify technical constraints
Add technology stack requirements

Example specification:

Feature: User Authentication
Stack: Next.js 14, Prisma, PostgreSQL
Description: Email-based authentication system with password reset
Acceptance Criteria:
- Email/password signup
- Login with credentials
- Password reset flow
- Session management
Technical Constraints:
- Must use Next-Auth
- JWT token-based

Development Workflow

Using CursorRules

CursorRules help maintain consistency in your codebase. Create a .cursorrules file in your project root to define coding standards and preferences.

For Ruby on Rails projects, you can use this comprehensive template:
Ruby on Rails CursorRules

Code Tagging

Use the @/ symbol to help CursorAI focus on relevant code:

@/src/components  # Focus on components
@/lib/utils      # Focus on utilities

This helps the AI understand context and generate more relevant code.

Save All Feature

Use "save all" in the CursorAI composer to write changes to files
If the button isn't visible, try resizing your window
Test changes before accepting them
You can still reject changes after saving

Advanced Features

Effective Prompting

Preparation
- Plan your prompts carefully
- Use simpler models for prompt refinement
- Think through what you want to achieve
Iteration
- Be patient with o1 model responses
- Provide clear, reasoned explanations
- Build on previous responses

Workflow Optimization

For exploration:

For architecture decisions:

Privacy and Security

Privacy Mode Options

Basic Privacy Settings
- Enable Privacy Mode to prevent code storage
- Note: Prompts are retained for 30 days by AI providers
Data Indexing
- Control automatic indexing
- Use manual indexing with "Compute Index"
- Understand what data is being indexed

API Key Usage

When using your API key:

Requests still go through Cursor's backend
Required for prompt construction
Consider this in your security planning

Best Practices

Model Selection
- Use Claude 3.5 for exploration and quick tasks
- Switch to o1 for critical decisions
- Match the model to the task complexity
Code Organization
- Use code tagging effectively
- Maintain a clear project structure
- Follow framework conventions
Documentation
- Document AI-specific commands
- Keep track of successful prompts
- Note any limitations or workarounds
Testing
- Test generated code thoroughly
- Use incremental changes
- Verify edge cases

Resources

Ruby on Rails .cursorrules Template
Cursor's official documentation
Community templates and examples
- https://playbooks.com/course/introduction-to-cursor
- https://cursor.directory/ .cursorrules for various frameworks

Conclusion

CursorAI is a powerful tool that can significantly enhance your development workflow. By understanding its capabilities and following these guidelines, you can make the most of its features while maintaining code quality and security.

Remember:

Choose the suitable model for your task
Plan your prompts carefully
Use privacy features appropriately
Test thoroughly
Document your successful patterns

With practice, CursorAI becomes an invaluable member of your development team, helping you write better code faster while maintaining high quality and security standards.

Testing External Services with RSpec, VCR, and WebMock in Ruby on Rails

David Paluy — Sat, 02 Nov 2024 22:20:05 +0000

Testing External Services with RSpec, VCR, and WebMock in Ruby on Rails

For quick setup, just run:

rails app:template LOCATION='https://railsbytes.com/script/X8Bsyo'

👉 View template source

Introduction

When building Rails applications that integrate with external services, it's crucial to have reliable tests that don't depend on actual HTTP requests. This tutorial will show you how to use VCR and WebMock to record and replay HTTP interactions in your RSpec tests.

Setup

First, add these gems to your Gemfile:

group :test do
  gem 'rspec-rails'
  gem 'vcr'
  gem 'webmock'
end

Run bundle install to install the gems.

Configuring VCR and WebMock

Create a new file at spec/support/vcr.rb:

require 'vcr'
require 'webmock/rspec'

# Disable all real HTTP connections, except to localhost
WebMock.disable_net_connect!(allow_localhost: true)

VCR.configure do |c|
  # Where VCR will store the recorded HTTP interactions
  c.cassette_library_dir = Rails.root.join('spec', 'cassettes')

  # Ignore localhost requests
  c.ignore_localhost = true

  # Tell VCR to use WebMock
  c.hook_into :webmock

  # Allow VCR to be configured through RSpec metadata
  c.configure_rspec_metadata!

  # Allow real HTTP connections when no cassette is in use
  c.allow_http_connections_when_no_cassette = true

  # Configure how requests are matched
  c.default_cassette_options = { 
    match_requests_on: [:method, :uri, :body] 
  }

  # Filter sensitive data before recording
  c.before_record do |interaction|
    interaction.request.headers['Authorization'] = '[FILTERED]'
  end

  # Ignore specific hosts
  ignored_hosts = ['codeclimate.com']
  c.ignore_hosts *ignored_hosts
end

# Configure RSpec to use VCR
RSpec.configure do |config|
  config.around(:each) do |example|
    options = example.metadata[:vcr] || {}
    options[:allow_playback_repeats] = true

    if options[:record] == :skip
      VCR.turned_off(&example)
    else
      custom_name = example.metadata[:vcr]&.delete(:cassette_name)
      generated_name = example.metadata[:full_description]
        .split(/\s+/, 2)
        .join('/')
        .underscore
        .tr('.', '/')
        .gsub(/[^\w\/]+/, '_')
        .gsub(/\/$/, '')

      name = custom_name || generated_name
      VCR.use_cassette(name, options, &example)
    end
  end
end

Using VCR in Your Tests

Here are some examples of how to use VCR in your specs:

Basic Usage

# spec/services/weather_service_spec.rb
RSpec.describe WeatherService do
  describe '#get_forecast' do
    it 'fetches weather data from the API' do
      service = WeatherService.new
      forecast = service.get_forecast('London')

      expect(forecast).to include('temperature')
    end
  end
end

Custom Cassette Names

RSpec.describe WeatherService do
  describe '#get_forecast' do
    it 'fetches weather data', vcr: { cassette_name: 'weather_api/london_forecast' } do
      # Your test code
    end
  end
end

It will make a first connection to the external service and record the response into a cassete

Skipping VCR

it 'makes real HTTP requests', vcr: { record: :skip } do
  # VCR will be disabled for this test
end

Best Practices

Sensitive Data: Always filter sensitive information like API keys and tokens:

VCR.configure do |c|
  c.filter_sensitive_data('<API_KEY>') { ENV['API_KEY'] }
end

Match Request Bodies: When testing POST requests, make sure to match on body content:

vcr: { 
  match_requests_on: [:method, :uri, :body],
  record: :new_episodes 
}

Regular Cassette Updates: Periodically re-record your cassettes to ensure they match current API responses:

Troubleshooting

Common Issues

Unmatched Requests: If VCR can't find a matching request, check:
- Request method (GET, POST, etc.)
- URL (including query parameters)
- Request body
- Headers (if matching on headers)
Playback Failures: If recorded responses aren't playing back:
- Verify the cassette file exists
- Check if the request matching criteria are too strict
- Ensure sensitive data is being filtered consistently

Conclusion

VCR and WebMock provide a robust solution for testing external service integrations in Rails. By following these patterns and best practices, you can create reliable, maintainable tests that don't depend on external services being available.

Remember to:

Filter sensitive data
Organize cassettes logically
Update cassettes periodically
Match requests appropriately
Handle errors gracefully

DEV Community: David Paluy

Codex CLI Developer Guide

Table of Contents

Quick Start

Install Codex CLI

Quick Examples

Resume Codex Sessions

Shell Shortcuts

examples

Optional aliases

Essential Configuration

Recommended config.toml

Settings - Deep Dive

Sandbox Modes

read-only - Code Analysis Only

workspace-write - Development Mode (Default)

danger-full-access - No Restrictions

Command-Line Overrides (-c flag)

YOLO Mode (--yolo)

Approval Policies

Profiles for Different Workflows

Verbosity - model_verbosity

Network Access

Environment Variables

Security Best Practices

Empowering AI Agents to Monitor Pull Request Status

# scripts/poll_ci.sh

AI Instructions

Exploring Agentic Workflow Patterns

Understanding Agentic Workflows

Why Agentic Patterns Matter

Navigating This Guide

Table of Contents

Network (Horizontal)

Hierarchical (Vertical)

Sequential

Parallel

Loop (Self-Healing)

Router (Agentic RAG)

Aggregator (Synthesizer)

Branching (Conditional Processing)

Ensemble (Voting or Consensus)

Cascade (Progressive Refinement)

Fallback (Error Handling)

Mastering Cursor Rules: A Developer's Guide to Smart AI Integration

What are Cursor Rules?

Three Types of Cursor Rules

1. Global AI Rules (Settings)

2. Project-Wide Rules (.cursorrules)

3. Pattern-Specific Rules (.cursor/rules/*.mdc)

Agentic Approach: The Game Changer

Pro Tips

1. Reference Architecture Using "@ syntax"

2. Strategic Glob Patterns

3. Combining Rules

4. Maintainable Organization

When Third-Party APIs Go Rogue

Strategies for Building Bulletproof Integrations

1. Configure Timeouts

Example (Net::HTTP)

2. Automatic Retries

Example Using Faraday with Retry

Faraday + faraday-retry

Retriable

3. Implement a Hard Rate Limiter

Example (Rails Model)

4. Decouple with an Interface

5. Asynchronous, Persistent Queuing

Rails ActiveJob Example

Conclusion

Lang Everything: The Missing Guide to LangChain's Ecosystem

LangChain: The Foundation

LangGraph: The Orchestrator

LangFlow: The Visual Builder

LangSmith: The Monitor

Making the Right Choice

Leveraging AI Tools for Modern Web Development

Overview

Tools Required

Step 1: Research with Perplexity AI

`read-only` - Code Analysis Only

`workspace-write` - Development Mode (Default)

`danger-full-access` - No Restrictions

`# scripts/poll_ci.sh`