Skip to main content

Claude Code

Claude Code – Quick Guide

1. Overview

This guide provides a quick reference for using Claude Code effectively within our RPA development workflow. It covers authentication, usage with repositories, and best practices for building Python-based RPA services using our standard stack:

  • FastAPI (web services)

  • Celery (background jobs)

  • PostgreSQL (database)

  • Redis (queue & caching)

2. Access & Login

  1. Open the Claude Code access link provided by the organization.

  2. Enter your company email address.

  3. Check your inbox for the login email.

  4. Click the secure login link (magic link).

  5. You will be automatically authenticated and redirected.

⚠️ Notes:

3. Using Claude Code with Repositories

Existing Repository

  1. Open the repository in your IDE.

  2. Connect Claude Code to the project context.

  3. Provide context explicitly:

    • Project structure

    • Key modules

    • Business logic

  4. Use Claude Code for:

    • Refactoring

    • Code explanation

    • Adding features

    • Writing tests

💡 Tip:
Always guide Claude with context:

"Given this service structure, extend the existing Celery task to handle retries and logging"

4. Best Practices for Using Claude Code

Prompting

  • Be specific and structured

  • Provide context (files, architecture, constraints)

  • Iterate incrementally instead of asking for everything at once

Code Review Mindset

  • Never blindly trust generated code

  • Validate:

    • Error handling

    • Edge cases

    • Security implications

    • Performance

Reusability

  • Ask for modular code

  • Prefer dependency injection patterns

  • Avoid monolithic functions

5. RPA Service Design Guidelines

Architecture Principles

  • Keep API layer thin (FastAPI)

  • Delegate logic to services

  • Use Celery for all asynchronous or long-running tasks

  • Ensure idempotency in RPA jobs

FastAPI (Web Layer)

  • Use routers to separate domains

  • Validate input with Pydantic models

  • Implement proper HTTP status codes

  • Add health check endpoints (/health)

Celery (Task Processing)

  • Use task queues per domain if needed

  • Configure retries with exponential backoff

  • Ensure tasks are:

    • Idempotent

    • Observable (logging + monitoring)

Example:

@celery.task(bind=True, autoretry_for=(Exception,), retry_backoff=True)
def process_job(self, job_id):
    ...

Redis

  • Use as:

    • Celery broker

    • Cache layer (short-lived data)

  • Avoid storing critical persistent data

PostgreSQL

  • Use transactions where needed

  • Design normalized schemas

  • Index frequently queried fields

  • Avoid heavy logic in DB unless necessary

6. Observability & Reliability

  • Add structured logging (JSON preferred)

  • Include correlation IDs for job tracking

  • Monitor:

    • Task failures

    • Queue backlog

    • API latency

7. Testing Strategy

  • Unit tests for services

  • Integration tests for API endpoints

  • Mock external dependencies

  • Validate Celery tasks independently

💡 Tip:
Ask Claude:

"Write pytest tests for this FastAPI endpoint including edge cases"

8. Common Pitfalls

  • ❌ Mixing business logic inside API routes

  • ❌ Non-idempotent Celery tasks

  • ❌ Missing retry strategies

  • ❌ Poor prompt quality leading to unusable code

  • ❌ Lack of validation on generated code

  1. Define requirement

  2. Ask Claude for a structured approach

  3. Generate initial implementation

  4. Review and refine manually

  5. Add tests

  6. Validate in local environment

  7. Submit PR

10. Final Recommendations

  • Treat Claude Code as a senior assistant, not an autonomous developer

  • Use it to accelerate, not replace, engineering decisions

  • Keep architecture ownership within the team

  • Continuously refine prompts for better output

11. File Handling via Bucket (BE → Worker)

In RPA scenarios, it is common to process files (documents, images, exports). Passing raw bytes directly through API requests or Celery messages is strongly discouraged.

Use an object storage bucket (e.g., S3-compatible) as an intermediary layer between Backend (BE) and Workers.

Flow

  1. Client uploads file to BE

  2. BE stores file in bucket

  3. BE sends a Celery task with a reference (NOT raw bytes):

    • file path / object key

    • metadata (optional)

  4. Worker retrieves file from bucket

  5. Worker processes file

  6. Worker stores result back in bucket (if needed)

  7. BE retrieves result or exposes it via API

Why NOT Pass Bytes Directly

  • ❌ Large payloads overload message broker (Redis)

  • ❌ Increased memory usage in workers

  • ❌ Serialization/deserialization overhead

  • ❌ Reduced reliability for large files

Best Practices

  • Always pass references, not data in Celery tasks

  • Use structured payloads:

    {
    "file_key": "uploads/job_123/input.pdf",
    "job_id": "123",
    "metadata": {...}
}

  • Use temporary or namespaced paths per job

  • Implement cleanup policies for old files

  • Version outputs when needed (e.g., retries or reprocessing)

Example

FastAPI (BE)

@app.post("/process")
async def process(file: UploadFile):
    key = f"uploads/{uuid4()}/{file.filename}"
    await bucket_client.upload(file.file, key)

    process_job.delay({
        "file_key": key
    })

    return {"status": "accepted"}

Celery Worker

@celery.task
def process_job(payload):
    file_bytes = bucket_client.download(payload["file_key"])

    result = do_processing(file_bytes)

    output_key = payload["file_key"].replace("uploads", "results")
    bucket_client.upload_bytes(result, output_key)

Additional Suggestions

  • Use signed URLs when direct access is needed

  • Add checksum/hash validation for file integrity

  • Log file references (never full content)

  • Monitor bucket usage and size

No Comments
Back to top