However longer inputs sometimes would generate errors. Longer inputs meant longer system prompts and longer responses.

The logs showed:

Analysis failed: expected ',' or '}' after object value

Claude was generating valid-looking JSON that wasn’t actually valid. A dropped comma deep in a large response object. The longer the response, the more likely this happened.

The Old Approach: Prompt Engineering + Defensive Parsing

My system prompt included a 28-line block demanding JSON output:

SYSTEM_PROMPT = <<~PROMPT
  ...
  CRITICAL INSTRUCTIONS:
  - You MUST ALWAYS respond with valid JSON. No exceptions. No explanations outside JSON.
  - NEVER respond with plain text - always use the JSON format.

  You MUST ALWAYS respond in JSON format with the following structure (no exceptions):
  {
    "score": 0-100,
    "level": "low|medium|high",
    "summary": "Brief overall assessment",
    "items": [
      {
        "title": "Issue name",
        "description": "What's wrong",
        "severity": "low|medium|high"
      }
    ],
    "recommendations": [
      "Specific actionable suggestion 1",
      "Specific actionable suggestion 2"
    ]
  }
PROMPT

Despite all the shouting in the prompt, Claude would sometimes:

• Wrap the JSON in markdown code fences (```json ... ```)
• Add explanatory text after the closing brace
• Drop commas in deeply nested objects on long responses
• Return plain text when it decided the input wasn’t suitable for analysis

So I built a pipeline of defensive code to handle all of this.

Step 1: Extract JSON from whatever Claude returned. A brace-matching parser that stripped markdown fences, found the first {, tracked nesting depth while respecting string escaping, and separated trailing notes:

def extract_json_and_note(text)
  text = text.strip
  if text.start_with?("```")
    text = text.sub(/A```(?:json|JSON)?s*/, "").sub(/s*```z/, "").strip
  end

  start_idx = text.index("{")
  return [text, nil, false] if start_idx.nil?

  brace_count = 0
  in_string = false
  escape_next = false

  text[start_idx..].each_char.with_index do |char, idx|
    if escape_next
      escape_next = false
      next
    end
    case char
    when "\" then escape_next = true if in_string
    when '"'  then in_string = !in_string unless escape_next
    when "{"  then brace_count += 1 unless in_string
    when "}"
      brace_count -= 1 unless in_string
      if brace_count == 0
        end_idx = start_idx + idx
        json_text = text[start_idx..end_idx]
        note = text[(end_idx + 1)..].strip.presence
        return [json_text, note, true]
      end
    end
  end

  [text, nil, false]
end

Step 2: Normalize missing fields because Claude might omit arrays for edge cases:

def normalize_response!(result)
  result["score"] ||= 0
  result["level"] ||= "unknown"
  result["summary"] ||= "Analysis complete"
  result["items"] ||= []
  result["recommendations"] ||= []
  result["score"] = result["score"].to_i if result["score"].is_a?(String)
end

Step 3: Validate the structure because even after parsing, I couldn’t trust it:

def validate_response_structure!(result)
  required_keys = %w[score level summary items recommendations]
  missing_keys = required_keys - result.keys
  raise "Invalid response structure: missing keys #{missing_keys.join(', ')}" if missing_keys.any?

  score = result["score"]
  unless score.is_a?(Integer) && score >= 0 && score <= 100
    raise "Invalid score: must be integer 0-100, got #{score.inspect}"
  end

  %w[items recommendations].each do |key|
    unless result[key].is_a?(Array)
      raise "Invalid #{key}: expected array, got #{result[key].class}"
    end
  end
end

All of this existed because I was asking an LLM to format its own output as JSON via natural language instructions. I was writing a fragile parser for a format the model was never constrained to produce.

The Fix: Tool Use

Anthropic’s tool use API (also called function calling) lets you define a JSON schema that Claude must conform to. Instead of asking Claude to output JSON, you tell the API: “call this function with these typed parameters.” Claude’s response is guaranteed to match the schema.

Here’s the schema definition:

ANALYSIS_TOOL = {
  name: "analyze",
  description: "Return the structured analysis results",
  input_schema: {
    type: "object",
    required: ["score", "level", "summary", "items", "recommendations"],
    properties: {
      score: { type: "integer", description: "Overall score from 0 (safe) to 100 (dangerous)" },
      level: { type: "string", enum: ["low", "medium", "high"] },
      summary: { type: "string", description: "Brief overall assessment" },
      items: {
        type: "array",
        items: {
          type: "object",
          required: ["title", "description", "severity"],
          properties: {
            title:       { type: "string" },
            description: { type: "string" },
            severity:    { type: "string", enum: ["low", "medium", "high"] }
          }
        }
      },
      recommendations: { type: "array", items: { type: "string" } }
    }
  }
}.freeze

The API call adds two parameters:

response = client.messages.create(
  model: model,
  max_tokens: max_tokens,
  system: [{ type: "text", text: system_prompt }],
  messages: [{ role: "user", content: user_message }],
  tools: [ANALYSIS_TOOL],
  tool_choice: { type: "tool", name: "analyze" }
)

tools: defines the schema. tool_choice: with type: "tool" forces Claude to use it — no chance of returning prose instead.

Response extraction is three lines:

tool_block = response.content.find { |b| b.type.to_s == "tool_use" }
raise "No tool_use block in response" unless tool_block
result = tool_block.input.transform_keys(&:to_s)

That’s it. tool_block.input is already a parsed hash. No JSON.parse, no brace matching, no markdown stripping, no comma repair.

The Result

Deleted: ~160 lines from the service, ~250 lines from tests..

Added: ~30 lines for the schema definition, 2 parameters on the API call, 3 lines of response extraction.

The system prompt shrank too. The 28 lines of “YOU MUST RESPOND IN JSON” instructions disappeared entirely. The prompt now focuses on what to analyze, not how to format the output.

The user message went from "Analyze this and respond with JSON only:" to just "Analyze this:".

When Should You Use This?

Any time you want structured output from an LLM. If you’re writing regex to fix JSON commas, building brace-matching parsers, or adding “RESPOND IN JSON ONLY” to your prompts: switch to tool use. The schema is self-documenting, the output is guaranteed valid, and you delete code instead of writing it.

The one caveat: tool use constrains the structure but not the content. Claude can still put whatever it wants in a string field. You still need to validate that a score is in a sensible range or that enum values match your expectations. But “validate the values” is a much smaller problem than “parse arbitrary text that might be JSON.”

Why I Built This

I’ve signed a enough contracts over the years, and I was never quite sure if I was missing something important buried in the legal language. I’d skim through them, but let’s be honest – I didn’t understand half of it. Getting a lawyer to review every contract is also just not something I’m going to do, unless it’s something really big.

I figured: AI is pretty good at reading and understanding text now. And based on how many of these AI contract analysis tools are out there, it’s the new TODO app in the age of AI.

The Stack

I went with a Rails 8 monolith because I wanted something I could ship quickly and maintain solo:

• Rails 8 with Hotwire (Turbo + Stimulus)
• Anthropic’s Claude API
• Solid Queue for background jobs with priority queues (paid users get faster processing)
• Solid Cache for caching and rate limits
• Stripe for subscriptions and billing
• Tesseract OCR for extracting text from scanned images (JPG, PNG, WebP, HEIC)
• Kamal for deployment

Everything runs in Docker containers. No separate frontend framework, no microservices. Just a straightforward Rails app that does one thing well.

Technical Security Challenges

1. File Processing Security
   • Magic byte validation – Don’t trust file extensions. I check the actual file signature to verify it’s really a PDF or DOCX.
   • Size limits – DOCX files are zip archives, so I enforce size limits before decompression to prevent zip bombs.
   • Immediate deletion – Original files are deleted right after text extraction. No long-term storage of sensitive documents.
   • Command injection prevention – Only use safe extraction tools, never shell out with user-provided filenames.
2. Server Access
   • Firewall at the provider level
   • Firewall at the node level (ufw)
   • ssh through certs only, limit access to specific IP’s
   • Cloudflare
3. Application Security
   • Devise authentication – Industry-standard auth framework
   • CSRF protection – Rails CSRF tokens on all POST/PUT/PATCH/DELETE requests
   • UUID-based URLs – Guest contracts use UUIDs (prevents enumeration attacks)
   • Rate Limits (Rack::Attack)
   • CSP Policy
     • No unsafe-eval – Prevents eval() attacks
     • Whitelisted script sources – Only self, HTTPS, Stripe, Cloudflare allowed
     • No object embeds – object_src :none blocks Flash/plugin attacks
     • Nonce-based scripts – Importmap scripts use session-based nonces
     • HTTPS enforced – All resources loaded over HTTPS
   • Input Validation
4. Fraud Prevention
   • Email history tracking – SHA256 email hashing – Email hashes stored, not plain emails
5. Payment Security
   • Stripe webhook verification – Signature validation on all webhook events
   • No card storage – Stripe handles all payment details
6. Secret Management
   • Rails credentials – All secrets in encrypted credentials.yml.enc
7. XSS Prevention
   • Automatic HTML escaping
   • CSP headers – Content Security Policy blocks inline scripts
8. Transport Security
   • HTTPS everywhere – All resources loaded over HTTPS
   • Secure cookies – Session cookies marked secure in production
   • HSTS headers – Forces HTTPS connections
9. DoS Prevention
   • Job queues – Background processing prevents request timeouts
   • Priority queues – Paid users get separate high-priority queue
   • Rate limiting – Comprehensive rate limits across all endpoints
   • Query optimization – Indexed queries prevent slow lookups

Try it

Demo (no signup): https://clausyapp.com/contracts/new?demo=hn

Full app: https://clausyapp.com

It’s not legal advice – I’m very explicit about that – but it can help you spot things you might want to ask a lawyer about.

Problem: you have a self-hosted Sentry server behind a firewall and you want to report your frontend errors.

One way to accomplish it is by modifying Sentry dsn to send it to your backend and then proxying them to the Sentry server.

First, let’s set up a new route:

post 'frontend_errors/api/:project_id/store', to: 'frontend_errors#create'

It has to follow a specific pattern to work with the Sentry frontend library. The only thing you can change in the above is frontend_errors – pick whatever name you want. The code above will expect you to have a FrontendErrorsController.

Now, the FrontEndErrorsController needs to redirect to your actual Sentry server in the format that Sentry expects. Let’s create a new class to handle it:

class SentryProxy
  # This could be different based on your Sentry version.
  # Look into raven-sentry gem codebase if this doesn't work
  # Look for http_transport.rb files - https://github.com/getsentry/sentry-ruby/blob/f6625bd12fa5ef86e4ce6a1515e8a8171cea9ece/sentry-ruby/lib/sentry/transport/http_transport.rb
  PROTOCOL_VERSION = '5'
  USER_AGENT = "raven-ruby/#{Raven::VERSION}"

  def initialize(body:, sentry_dsn:)
    @body = body
    @sentry_dsn = sentry_dsn
  end

  def post_to_sentry
    return if @sentry_dsn.blank?

    sentry_connection.post do |faraday|
      faraday.body = @body
    end
  end

  private

  def sentry_connection
    Faraday.new(url: sentry_post_url) do |faraday|
      faraday.headers['X-Sentry-Auth'] = generate_auth_header
      faraday.headers[:user_agent] = "sentry-ruby/#{Raven::VERSION}"
      faraday.adapter(Faraday.default_adapter)
    end
  end

  def sentry_post_url
    key, url = @sentry_dsn.split('@')
    path, project_id = url.split('/')
    http_prefix, _keys = key.split('//')

    "#{http_prefix}//#{path}/api/#{project_id}/store/"
  end

  def generate_auth_header
    now = Time.now.to_i.to_s
    public_key, secret_key = @sentry_dsn.split('//').second.split('@').first.split(':')

    fields = {
      'sentry_version' => PROTOCOL_VERSION,
      'sentry_client' => USER_AGENT,
      'sentry_timestamp' => now,
      'sentry_key' => public_key,
      'sentry_secret' => secret_key
    }
    'Sentry ' + fields.map { |key, value| "#{key}=#{value}" }.join(', ')
  end
end

Now in your controller you can call it like this (assumes you can get your sentry_dsn on the backend):

def create
  SentryProxy.new(body: request.body.read, sentry_dsn: sentry_dsn).post_to_sentry

  head(:no_content)
end

And to make sure your frontend is properly configured, first import Sentry frontend libraries, then initialize them using:

 Sentry.init({
    dsn: `${window.location.protocol}//public_key@${window.location.host}/frontend_errors/0`});

public_key is supposed to be… your public key. You have to supply it in the dsn even if you’re getting the dsn key on the backend, otherwise, the Sentry frontend library will throw errors. 0 is the project id – the same idea, you have to supply it for the Sentry frontend to properly parse it. It doesn’t have to be real, as we’re reconstructing the Sentry url on the backend, and you can get proper keys/project id on the backend.

This should do it. Now you can configure Sentry frontend library to capture all errors, capture specific exceptions or messages.

OS: Ubuntu 18.04 LTS

When you need to use redis for cache and non-cache entries (e.g., ActionCable, Sidekiq…), the recommended approach is to create a separate redis instance. However, if you want a simpler setup, or just can’t get another instance for reasons, there is an option to use the same redis instance for multiple uses.

We need to make sure that Redis will not evict our important data (e.g., Sidekiq), while at the same time evicting old cache entries. We could use any of the volatile eviction policies:

• volatile-lru – remove least recently used keys where expiry is set
• volatile-random – removes keys at random where expiry is set
• volatile-ttl – evict keys with an expire set, and try to evict keys with a shorter time to live (TTL) first
• volatile-lfu (starting with Redis 4.0) – evict using approximated LFU among the keys with an expire set.

To set up the eviction policy on your redis instance, edit your /etc/systemd/system/redis.conf and set these parameters:

maxmemory 100mb
maxmemory-policy volatile-lfu

Then in your Rails config update your store to use redis cache store, if not using already:

  config.cache_store = :redis_cache_store, {
    url: ENV.fetch('REDIS_URL', 'redis://localhost:6379'),
    expires_in: 24.hours
  }

EncryptionError = Class.new(StandardError)

result, stderr, status = Open3.capture3("gpg --import #{@key_path}")
raise EncryptionError.new(stderr_data) unless status.success?

To encrypt data with a public key for a given recipient:

pgp_encrypt_command = "gpg -ear #{recipient} --always-trust --trust-model always --local-user #{recipient} --default-key #{recipient}"

encrypted_data, stderr_data, status = Open3.capture3(pgp_encrypt_command, stdin_data: data)
    raise EncryptionError.new(stderr_data) unless status.success?

Install Microsoft Azure Storage Explorer

Create some directory to run azurite from: `~/azurite`

Add storage.yml configuration for azurite (using the default dev account and key):

azurite_emulator:
  service: AzureStorage
  storage_account_name: 'devstoreaccount1'
  storage_access_key: 'Eby8vdM02xNOcqFlqUwJPLlmEtlCDXJ1OUzFT50uSRZ6IFsuFq2UVErCz4I6tq/K1SZFPTOtr/KBHBeksoGMGw=='
  container: 'container-name'
  storage_blob_host: 'http://127.0.0.1:10000/devstoreaccount1'

Update development.rb to use azurite_emulator:

config.active_storage.service = :azurite_emulator

Start azurite from the directory you created for azurite: azurite --location ~/azurite --debug ~/azurite/debug.log

Start Azure Storage Explorer, connect to local emulator, and create container-name blob container – the same container name you specified in the storage.yml file.

Start uploading to Azurite.

Note for Rails 5.2

Some changes have not been backported as of this post, and you have to monkey-patch ActiveStorage file as described here – http://www.garytaylor.blog/index.php/2019/01/30/rails-active-storage-and-azure-beyond-config/ – this allows us to work with azurite locally.

If you want to use the newer azure-storage-blob instead of the deprecated azure-storage and you’re on Rails 5.2, you have to do a bit more monkey-patching – otherwise, you’ll start getting No such file to load — azure/storage.rb“:

Add two empty files: lib/azure/storage/core/auth/shared_access_signature.rb, and lib/azure/storage.rb

Add this to config/initializers/active_storage_6_patch.rb (this is the current master version of the ActiveStorage module):

require "azure/storage/blob"
require 'active_storage/service/azure_storage_service'
module ActiveStorage
  # Wraps the Microsoft Azure Storage Blob Service as an Active Storage service.
  # See ActiveStorage::Service for the generic API documentation that applies to all services.
  class Service::AzureStorageService < Service
    attr_reader :client, :container, :signer

    def initialize(storage_account_name:, storage_access_key:, container:, public: false, **options)
      @client = Azure::Storage::Blob::BlobService.create(storage_account_name: storage_account_name, storage_access_key: storage_access_key, **options)
      @signer = Azure::Storage::Common::Core::Auth::SharedAccessSignature.new(storage_account_name, storage_access_key)
      @container = container
      @public = public
    end

    def upload(key, io, checksum: nil, filename: nil, content_type: nil, disposition: nil, **)
      instrument :upload, key: key, checksum: checksum do
        handle_errors do
          content_disposition = content_disposition_with(filename: filename, type: disposition) if disposition && filename

          client.create_block_blob(container, key, IO.try_convert(io) || io, content_md5: checksum, content_type: content_type, content_disposition: content_disposition)
        end
      end
    end

    def download(key, &block)
      if block_given?
        instrument :streaming_download, key: key do
          stream(key, &block)
        end
      else
        instrument :download, key: key do
          handle_errors do
            _, io = client.get_blob(container, key)
            io.force_encoding(Encoding::BINARY)
          end
        end
      end
    end

    def download_chunk(key, range)
      instrument :download_chunk, key: key, range: range do
        handle_errors do
          _, io = client.get_blob(container, key, start_range: range.begin, end_range: range.exclude_end? ? range.end - 1 : range.end)
          io.force_encoding(Encoding::BINARY)
        end
      end
    end

    def delete(key)
      instrument :delete, key: key do
        client.delete_blob(container, key)
      rescue Azure::Core::Http::HTTPError => e
        raise unless e.type == "BlobNotFound"
        # Ignore files already deleted
      end
    end

    def delete_prefixed(prefix)
      instrument :delete_prefixed, prefix: prefix do
        marker = nil

        loop do
          results = client.list_blobs(container, prefix: prefix, marker: marker)

          results.each do |blob|
            client.delete_blob(container, blob.name)
          end

          break unless marker = results.continuation_token.presence
        end
      end
    end

    def exist?(key)
      instrument :exist, key: key do |payload|
        answer = blob_for(key).present?
        payload[:exist] = answer
        answer
      end
    end

    def url_for_direct_upload(key, expires_in:, content_type:, content_length:, checksum:)
      instrument :url, key: key do |payload|
        generated_url = signer.signed_uri(
          uri_for(key), false,
          service: "b",
          permissions: "rw",
          expiry: format_expiry(expires_in)
        ).to_s

        payload[:url] = generated_url

        generated_url
      end
    end

    def headers_for_direct_upload(key, content_type:, checksum:, filename: nil, disposition: nil, **)
      content_disposition = content_disposition_with(type: disposition, filename: filename) if filename

      { "Content-Type" => content_type, "Content-MD5" => checksum, "x-ms-blob-content-disposition" => content_disposition, "x-ms-blob-type" => "BlockBlob" }
    end

    private
      def private_url(key, expires_in:, filename:, disposition:, content_type:, **)
        signer.signed_uri(
          uri_for(key), false,
          service: "b",
          permissions: "r",
          expiry: format_expiry(expires_in),
          content_disposition: content_disposition_with(type: disposition, filename: filename),
          content_type: content_type
        ).to_s
      end

      def public_url(key, **)
        uri_for(key).to_s
      end


      def uri_for(key)
        client.generate_uri("#{container}/#{key}")
      end

      def blob_for(key)
        client.get_blob_properties(container, key)
      rescue Azure::Core::Http::HTTPError
        false
      end

      def format_expiry(expires_in)
        expires_in ? Time.now.utc.advance(seconds: expires_in).iso8601 : nil
      end

      # Reads the object for the given key in chunks, yielding each to the block.
      def stream(key)
        blob = blob_for(key)

        chunk_size = 5.megabytes
        offset = 0

        raise ActiveStorage::FileNotFoundError unless blob.present?

        while offset < blob.properties[:content_length]
          _, chunk = client.get_blob(container, key, start_range: offset, end_range: offset + chunk_size - 1)
          yield chunk.force_encoding(Encoding::BINARY)
          offset += chunk_size
        end
      end

      def handle_errors
        yield
      rescue Azure::Core::Http::HTTPError => e
        case e.type
        when "BlobNotFound"
          raise ActiveStorage::FileNotFoundError
        when "Md5Mismatch"
          raise ActiveStorage::IntegrityError
        else
          raise
        end
      end
  end
end

To fix, run this on the command line:

xcode-select --install

this should trigger a popup with the invitation to install Xcode CLT.

gem install rufo

Create .rufo either in your project or home directory if you want to override default settings

trailing_commas false
quote_style :single
align_chained_calls true

Install a plugin for your favorite editor. Here’s one for VSCode – https://marketplace.visualstudio.com/items?itemName=siliconsenthil.rufo-vscode

Command + Shift + P
Type Shell
Select Command : Install code in PATH

Extensions

Rails

• Better Haml
• Cucumber (Gherkin) Full Support
• Ruby
• Ruby Solargraph
• ruby-rubocop

JavaScript

• ESLint
• Prettier

Git

• Git Lens

Elixir

• vscode-elixir

Other stuff

• pgFormatter
• Project Manager
• Bracket Pair Colorizer

Personal Settings

"editor.formatOnSave": true,
  "editor.fontLigatures": true,
  "editor.fontFamily": "FiraCode-Retina",
  "editor.fontSize": 18,
  "editor.renderIndentGuides": true,
  "files.exclude": {
    "**/.git": true,
    "**/node_modules": true,
    "**/bower_components": true,
    "**/tmp": true,
    "tmp/**": true,
    "**/vendor": true,
    "vendor": true,
    ".bundle": true,
    ".github": true,
    ".sass-cache": true,
    "features/reports": true
  },

  "editor.tabSize": 2,
  "prettier.singleQuote": true,
  "workbench.colorTheme": "Monokai",
  "window.zoomLevel": 0,
  "editor.renderWhitespace": "boundary",
  "editor.renderControlCharacters": true,

  "ruby.lint": {
    "rubocop": true,
    "ruby": true,
    "fasterer": true,
    "reek": false,
    "ruby-lint": false
  },
  "editor.quickSuggestions": {
    "strings": true
  },

  "cucumberautocomplete.steps": [
    "features/step_definitions/*.rb",
    "features/step_definitions/**/*.rb",
    "features/step_definitions/**/**/*.rb"
  ],
  "cucumberautocomplete.syncfeatures": "features/*feature"

Some common exclusions for .solagraph.yml (can place it in the root of your project)

---
include:
- "app/**/*.rb"
- "lib/**/*.rb"
- "engines/engine_name/app/**/*.rb"
- "engines/engine_name/lib/**/*.rb"
- "config/**/*.rb"
exclude:
- app/javascript/**/*
- node_modules/**/**
- spec/**/*
- test/**/*
- vendor/**/*
- ".bundle/**/*"
- .bundle/**/*
- uploads/**/*
- .bundle/**/*
- .git/**/*
- engines/engine_name/.bundle/**/*
- engines/engine_name/vendor/**/*
- coverage/**/*
require: []
domains: []
reporters:
- rubocop
- require_not_found
plugins: []
require_paths: []
max_files: 5000
plugins:
- runtime

group :test, :development do
  gem 'database_cleaner'
  gem "rspec-rails", "~> 3.6.0"
  gem 'selenium-webdriver'
end

group :test do
  gem "capybara", "~> 2.14.0"
end

rails_helper:

config.use_transactional_fixtures = false

  config.before(:suite) do
    DatabaseCleaner.clean_with(:truncation)
  end

  config.before(:each) do
    DatabaseCleaner.strategy = :transaction
  end

  config.before(:each, js: true) do
    DatabaseCleaner.strategy = :truncation
  end

  config.before(:each) do
    DatabaseCleaner.start
  end

  config.after(:each) do
    DatabaseCleaner.clean
  end

  #Puma makes it possible to run RSpec with ActionCable
  Capybara.server = :puma

  Capybara.register_driver :selenium_chrome do |app|
    Capybara::Selenium::Driver.new(app, browser: :chrome)
  end
  Capybara.javascript_driver = :selenium_chrome

And, the driver:

brew install chromedriver