
I've been writing code with LLMs since summer 2024. The way I use them has changed quite a bit in that time, so this post is an attempt to document those changes and how I currently use LLMs to build and maintain [Boords](https://boords.com).

I've been a web developer for almost 20 years now, and I can confidently say using LLMs, in particular Claude Code, is the biggest productivity boost I've ever experienced.

The pace things are moving this will likely quickly become outdated, and I'm not suggesting any of these approaches is the single _best_ way, just documenting what works for me.

My current workflow is primarily [Claude Code](https://www.anthropic.com/claude-code) with [Cursor](https://cursor.com) as my IDE (mainly for the AI-enabled autocomplete at this point), and [Warp](https://www.warp.dev/) as my terminal.

## Prerequisites & Principles

To get the most out of using LLMs for development work, follow the same principles you would when working with another developer.

- **Know how to code**. You MUST know what good looks like. If you don't know what you're looking at, it's impossible to know if there are errors or edge cases that will cause issues later on.
- **LLM = very well-read junior developer**. Good results require writing effective product requirements documents and clearly articulating what you want.
- **Work in small chunks**: Create small, well-defined tasks, review output, then move on.
- **Commit early, commit often**. Work on a feature branch, ensure everything is committed before starting a new task.

## Level 0 - Use a web-based LLM

In short: copy/paste code snippets into Claude/ChatGPT and ask for changes.

This is a good way to get started, but it's difficult to do anything complex or provide additional context and results are often mixed. I used this approach for a few months so it can work, but it's not a good long-term solution for serious development work.

## Level 1 - LLM-enabled IDE (e.g. Cursor)

A step up from web-based LLMs, [Cursor](https://cursor.com) embeds AI support into VSCode. It's much easier to add project context and the AI-enabled auto-complete was a true "Aha" moment for me.

Cursor is great for small changes and general grunt work, and I still use it together with Claude Code (see below), but code quality varies for more complex tasks, bug fixes etc.

## Level 2 - Claude Code

[Claude Code](https://www.anthropic.com/claude-code) is a command-line interface and is, at time of writing, state of the art for AI-enabled development. It has full project context from the outset and better workflow support for complex tasks.

At it's simplest, you can fire up the CLI and enter a task, e.g.:

```plaintext
$ claude
---
Extract ComponentX from path/to/BigComponent.tsx into a new file called ComponentY.tsx
```

Results with CC tend to be much better that Cursor et al, largely due to how good the underlying model is at interpreting/writing code, but fundamentally the workflow is the same.

## Level 3 - Claude Code with Task Management

Eventually you'll reach a point where you find it cumbersome to write complex tasks directly in the CLI. For more complex work (or indeed parallel tasks), you need a task managament system.

Claude Code automatically creates a `.claude/` directory in your project root after setup.

To manage tasks, create a new `.docs/` folder with subfolders for `todo`, `plans`, and `reference`, and a `commands` subfolder in `.claude`:

### Claude Code Structure

```plaintext
.claude/ ← auto-generated by claude on project setup
-- commands/ ← custom commands
.docs/
-- todo/ ← your markdown tasks
-- plans/ ← written by claude
-- reference/ ← reference documentation

...(the rest of your codebase)
```

### Workflow overview

1. **Write a Todo**. Write a markdown file in `.docs/todo/` outlining your change.
2. **Ask Claude to create a plan**. Ask Claude to create a plan (NOT to implement) the task you've just written in `.docs/todo/my-task.md`. This will create a new file in `.docs/plans/`, e.g. `.docs/plans/my-task-plan.md`
3. **Review the plan (new session)**. Manually review the plan to catch any obvious errors. You can also ask Claude to review it's own plan in a new session.
4. **Implement the plan (new session)**. Ask Claude to implement `.docs/plans/my-task-plan.md`
5. **Review the implementation (new session)**. Ask Claude to review changes in light of the plan, looking for areas of significant improvement, edge cases, etc.

### Custom Commands

To implement this it's helpful to create custom commands in your `.claude/` subfolder:

```plaintext
.claude/
-- commands/
---- plan.md
---- plan-review.md
---- implement.md
---- implementation-review.md
```

Each markdown file contains instructions on what to do at a given stage. For example, my `plan.md` file looks like this:

```plaintext
You are a senior full-stack software engineer. Your objective is to write a markdown document in `/.docs/plans` that specifies how to achieve the following. Include a link to this original todo in your plan.

Plan the task in the $ARGUMENTS markdown file located in /.docs/todo

ultrathink.
```

Note: `ultrathink` triggers the deepest thought the model is capable of. It's slower, but good to use as a default.

You can then use these commands in the cli at each stage of your workflow, e.g.:

```plaintext
$ claude
---
/project:plan .docs/todo/my-task.md
```

Once this is done, you'll have a new plan document and you're ready to review and move on to the next stage of the workflow:

```plaintext
...
.docs/
-- todo/
---- my-task.md
-- plans/
---- my-task-plan.md ← Claude's plan
...
```

Now you can move on to the _review_ and _implement_ stages of the workflow.

### Advanced: Multiple Claude Instances

Once you're comfortable with the workflow, you can run multiple Claude Code instances at the same time. I generally limit to two, one planning, one executing, while I'm writing a new `todo.md`.

## Next Steps: Using MCPs

MCP (Model Context Protocol) is a way for LLMs to use external services, APIs, etc. Setting up an MCP is beyond the scope of this article, but a couple that I use regularly are:

- [zen-mcp-server](https://github.com/BeehiveInnovations/zen-mcp-server). Allows Claude to talk with other LLMs (e.g. Gemini, o3) to come up with the best possible solution to a problem. New favourite.
- [Rollbar](https://docs.rollbar.com/docs/mcp-server-setup). Gets information about errors in our Rails stack, and (with a custom command) can identify the source of the error and propose a solution.
- [context7](https://github.com/upstash/context7). Fetches up-to-date documentation for a given library.



_To-do lists do not prefigure masterpieces. An over-engineered task management setup can extinguish the spark required for great creative work._

I used to practice yoga every morning. I would get up before sunrise and make my way to the studio with a handful of other bleary-eyed adherents. Most days, it was unremarkable. Some days, it was life-changing. 

'Good' practice days were infuriatingly unpredictable. They were entirely outside of my control. No amount of planning would make the slightest bit of difference. The harder I tried to force a new pose, the less likely I was to get it. All I could do was get enough sleep and keep showing up. 

Task management is appealing because it helps us feel in control of our work. But the paradox is that genuinely creative work is not within our control, or at least not reducible to a task list. Great creative work flows from the part of us beyond to-do lists, beyond planning. Whether that's our subconscious or something greater will depend on your world view. But whatever it is, it doesn't give a damn about inbox zero. 

Task management can help you take care of the necessary chores of life, but you cannot point it directly at your unruly subconscious, whose participation is a prerequisite for great creative work. Task management sets the stage but is not an end in itself. There is no magic productivity machine that spits out masterpieces.  

When I catch myself creating elaborate to-do lists or switching productivity setups, I try to think back to those early mornings on the mat. Keep it simple. Get enough sleep and keep showing up. Most of the time, it will be unremarkable. Sometimes, it will be life-changing. 



In January of 2021, I redesigned the Boords pricing page to reframe annual plans as discounts. I borrowed the idea from Manuel Frigerio's post on [reframing discounts](https://blog.friger.io/how-reframing-discounts-led-to-a-4x-increase-in-yearly-plans/).

<figure>
  <img src='https://img.jame.sc/210408-pricing-discount.gif' alt='Annual Pricing Discount' />
  <figcaption>Reframing the annual price as a discount</figcaption>
</figure>

Here's what happened:

<figure>
  <img src='https://img.jame.sc/210408-monthly-vs-yearly-subs.png' alt='Monthly vs Yearly' />
</figure>

While absolute plan numbers increased, the percentage of annual vs monthly subscriptions did not (in fact they are generally lower). I take this to mean that for our audience, reframing annual plans as discounts doesn't work, but the new pricing page layout is more effective at converting customers. 

Here's the old pricing page for reference. The plans run from low to high, whereas the new page uses high to low, which has been shown to boost conversion.

<figure>
  <img src='https://img.jame.sc/210115-original-pricing.jpeg' alt='Pre-January Boords pricing page' />
  <figcaption>Pre-January Boords pricing page</figcaption>
</figure>

Of course, the pricing page doesn't exist in isolation, and we've added several new product landing pages with new creative, which certainly has had an effect. 

<figure>
  <img src='https://img.jame.sc/210408-animatic-hero.gif' alt='Creative from the new animatic tool landing page' />
  <figcaption>Creative from the new animatic tool landing page</figcaption>
</figure>

On a technical note, I was able to gather the annual vs monthly data using a Stripe sigma query:

``` sql
with subscriptions_by_interval as (
  select
    prices.recurring_interval as BillingInterval,
    count(prices.recurring_interval) as Subscribers
  from
    subscriptions
    inner join prices on subscriptions.price_id = prices.id
    left join customers on subscriptions.customer_id = customers.id
  where
    prices.unit_amount > 0
    and month(subscriptions.created) = 1 -- Change month number
    and year(subscriptions.created) = 2021 -- Change year
  group by
    prices.recurring_interval
  order by
    prices.recurring_interval asc
)
select
  BillingInterval as "Billing Interval",
  Subscribers,
  Subscribers * 100 / t.s AS "% of total"
from
  subscriptions_by_interval
  CROSS JOIN (
    SELECT
      SUM(Subscribers) AS s
    FROM
      subscriptions_by_interval
  ) t
```

Even though the experiment didn't boost the monthly to annual ratio, I'm delighted to achieve a higher-converting page overall.  

My next step is to re-implement original monthly / annual toggle and see if that compounds the positive effect of the new pricing page design.



<figure>
  <img src='https://img.jame.sc/resting-heart-rate.jpg' alt='Resting Heart Rate' />
  <figcaption>My resting heart rate data 2019-2021, captured from my Apple Watch (screenshot composed from Health app)</figcaption>
</figure>

I’ve had my Apple Watch since early 2019, or a little under 2 years at the time of writing. Throughout our time together it has been dutifully recording my heart rate as I go about my day. I haven’t paid much attention to it, so I was surprised to learn that now - in January 2021 - my resting heart rate is a full 12 BPM (just over 22%) lower than it was back in early 2019. That’s despite the pandemic, associated lockdowns, and the birth of our second son (although to be fair my wife did a lot of the legwork on that particular day). Nevertheless, a drop from 59 to 47BPM feels worthy of investigation.  

## Environment

I lived in London for 14 years, and in autumn 2019 my family and I moved to a relatively small rural village in Hampshire. It’s of course literally much quieter than it was in London, and I’m outside 'in nature' a lot more - be it in the garden, running, or on a walk with the family. It’s hard to extract correlation from causation as being outside is tightly coupled with exercise, but I think it's fair to assume a quiet, leafy environment is beneficial to my health. 

## Exercise

This is the obvious change. I run more. I used to walk a lot in London (well over 10,000 steps daily) and did some irregular strength training. Now I run about 3 miles 3 times a week. I also do 5 minutes of strength training most days, together with a few minutes of yoga to keep the rust out. It's not particularly intense - I often feel guilty that I haven't worked out 'hard enough' - but it's very sustainable, and I believe I'm now seeing the compounding effects of consistency pay off. I doubt I would have stuck to a more strenuous routine. 

## Diet

My diet basically hasn’t changed. It could certainly be better - I still have a sweet tooth and a penchant for a drop of Japanese whiskey - but my 2021 diet is broadly similar to my 2019 diet. I've been experimenting with intermittent fasting 4 days a week since September 2020, but bottom line, I don't believe food is a factor. 

## Commuting

Or lack thereof. My commute is now a brisk 8-second walk from the house to the garage, where I work in the converted loft space. Plainly this is much less stressful than getting on the dreaded Northern Line at rush hour, which often drew comparison with the battle for Middle Earth. My subsequent pre-pandemic commute into London was longer – about 1h20m, followed by a 45-minute walk - but certainly less stressful than the tube. Either way, I’d be very surprised if removing the regular inherent stress of travel from my life hasn’t been a factor. 

## Surprise

Perhaps the most interesting part of this is that it caught me by surprise. I don’t subjectively ‘feel’ much healthier than I was 18 months ago. But here we are. I guess health improvements are so gradual that unless you go from no exercise whatsoever and a terrible diet, to the polar opposite, you’re unlikely to see a drastic change in your energy levels. I think I’m quite an optimistic person, so at any given point over the last 2 years I could have likely said something positive about my exercise habits. 

Basically, I've learned that I'm terrible at assessing my own health and that the cold, rational eye of technology is a pretty good way to get some objectivity. And if that's not a great justification for buying a new Apple Watch, I don't know what is.



Using Docker may seem like overkill for a local Next.js project, and indeed, perhaps it is. However there as some unique requirements to get hot reloading working in a Docker development environment which are worthy of note. I hope this configuration will be useful either in isolation, or when integrating a Next.js app into a larger service architecture.

### Prerequisites:

- [Docker](https://www.docker.com/) installed on your local machine
- A working [Next.js](https://nextjs.org/) app

## Step 1. Create a Dockerfile

In the root of your Next.js project, create your Dockerfile. See the inline comments for a description of each step: 

```docker
# Dockerfile

# Use node alpine as it's a small node image
FROM node:alpine

# Create the directory on the node image 
# where our Next.js app will live
RUN mkdir -p /app

# Set /app as the working directory
WORKDIR /app

# Copy package.json and package-lock.json
# to the /app working directory
COPY package*.json /app

# Install dependencies in /app
RUN yarn install

# Copy the rest of our Next.js folder into /app
COPY . /app

# Ensure port 3000 is accessible to our system
EXPOSE 3000

# Run yarn dev, as we would via the command line 
CMD ["yarn", "dev"]
```

## Step 2. Create docker-compose.yml

Again in the root of your Next.js project, create `docker-compose.yml`:

```yaml
# docker-compose.yml

version: "3"

services:
  web:
    build:
      context: .
      dockerfile: Dockerfile
    container_name: web
    restart: always
    volumes:
      - ./:/app
      - /app/node_modules
      - /app/.next
    ports:
      - 3000:3000
```

This is a very simple compose file, as we only have one service. The key point is the `volumes` attribute. By referencing the root of our app (`./:/app`), our node modules folder (`/app/node_modules`), and Next.js (`/app/.next`) we ensure our Next.js app can 'see' the changes we make through our Docker image, and therefore trigger hot reloading when we change a file.

## Step 3. Update next.config.js

The final change for hot reloading is to add webpack middleware so we poll for changes. Update your `next.config.js` file to include the following: 

```jsx
// next.config.js

module.exports = {
  webpackDevMiddleware: config => {
    config.watchOptions = {
      poll: 1000,
      aggregateTimeout: 300,
    }
    return config
  },
  ...
}
```

## Step 4. Build your image

Now you're ready to build your Docker image! Run compose with the `--build` switch and in a minute or so you should have a fresh node image running your Next.js app in all it's containerised glory (thanks to Docker's caching mechanisms, subsequent builds are a lot faster). 

```bash
$ docker-compose up -d --build
```

Fire up `[localhost:3000](http://localhost:3000)` in your browser, and any changes you make will be instantly reflected. No need to `docker-compose down / up`  every time. Pretty sweet. 

## References

Many thanks to these posts whose authors pointed me in the right direction: 

- [Next.js + Docker. Made easy.](https://dev.to/kumar_abhirup/next-js-docker-made-easy-2bok)
- [Docker: Live / Hot Reloading with Next.js](https://medium.com/@binyamin/docker-live-hot-reloading-with-next-js-bf3aa0c6b798)



_TLDR; make sure you `set re=0` in your vimrc or Typescript syntax highlighting
will be painfully slow_

## The Problem

In Vim 8, Typescript syntax highlighting is insanely slow, to the point of being unusable. Opening a typescript file can result in several seconds of editor freeze, an enormous node process running in the background, and finally a failure message `'redrawtime' exceeded, syntax highlighting disabled`. Needless to say, this is not conducive to a productive development experience. 

## The Solution

The issue is syntax highlighting, more specifically the regex engine Vim uses under the hood to facilitate it. Using the 'old' regex engine incurs [major performance penalties](https://github.com/HerringtonDarkholme/yats.vim#config), as I found to my cost. 

In a nutshell you **must set `re=0` explicitly in your vimrc** or you're gonna have a bad time:

```bash
# .vimrc
syntax on
" Use new regular expression engine
set re=0
```

HT to this post on [slow syntax highlighting in Vim](https://www.chunkhang.com/blog/slow-syntax-highlighting-in-vim) which pointed me in the right direction. 

## Bonus: Finding slow Vim plugins

While debugging this issue I spent some time profiling vim to see what was up. This profiling method mentioned in [this SO thread](https://stackoverflow.com/questions/12213597/how-to-see-which-plugins-are-making-vim-slow) was particularly useful.

### Step 1. Profile

```bash
:profile start profile.log
:profile func *
:profile file *
" Do the 'slow' stuff in Vim
:profile pause
:noautocmd qall!
```

This creates a new file called `profile.log`. 

### Step 2. Open profile.log

```bash
FUNCTION  <SNR>69_Highlight_Matching_Pair()
    Defined: /usr/local/Cellar/vim/8.2.1900/share/vim/vim82/plugin/matchparen.vim:40
Called 39 times
Total time:  81.354370
 Self time:  81.353935
```

Open `profile.log` and move to the bottom of the file. You'll see a list of functions, ordered by execution time. If Vim is slow, it's a useful starting point.



A fast, responsive development process is important. You don't want to be waiting around for 45 seconds for your Rails app to rebuild every time you make a change. But that's exactly the situation I found myself in this week. I went down a bit of a rabbit hole diagnosing the problem and dug up some useful Rails profiling tools in the process. 

## Rack Mini Profiler

[rack-mini-profiler](https://github.com/MiniProfiler/rack-mini-profiler) is the go-to Rails profiling gem and with good reason. It gives you a little widget in the corner of your app which shows you how long the page took to render, and where that time was spent. Here's a screengrab from the aforementioned ~45 second load time page: 


![rack mini profiler](https://img.jame.sc/rails-dev-performance-000.png)


The [flamegraph](https://github.com/SamSaffron/flamegraph) gem is often used with [rack-mini-profiler](https://github.com/MiniProfiler/rack-mini-profiler). While flamegraphs didn't help me in this instance, [this fantastic article from Justin Weiss](https://www.justinweiss.com/articles/a-new-way-to-understand-your-rails-apps-performance/) details how to use them. 

## DevTrace

Scout's [DevTrace](https://scoutapm.com/devtrace) offers much of the same information as Rack Mini Profiler, but with a slicker interface, and more contextual detail. In my case I was able to see that the app was spending a lot of time in Middleware - something Rack Mini Profiler didn't highlight. 

![Devtrace](https://img.jame.sc/rails-dev-performance-001.png)

## Chrome Rails Panel

[Chrome Rails Panel](https://chrome.google.com/webstore/detail/railspanel/gjpfobpafnhjhbajcjgccbbdofdckggg/related) is a Chrome Extension which shows you app profiling information in Chrome Dev tools. While it still requires an additional gem (`meta_request`), it doesn't add a button to your UI like DevTrace or Rack Mini Profiler. A good option if you want to keep your UI clean.

![Chrome Rails Panel](https://img.jame.sc/rails-dev-performance-002.png)

## Test response time with CURL

Profiling aside, I found myself refreshing my browser repeatedly while debugging my slow dev environment. This got old, fast. Thankfully, there's a better way - use curl from the command line:

```bash
$ curl 'http://localhost:5000' -s -o /dev/null -w  "%{time_starttransfer}\n"
```

This makes a web request to `localhost:5000` and spits out the response time. Easy peasy.

## Resources

- [Rack Mini Profiler](https://github.com/MiniProfiler/rack-mini-profiler)
- [DevTrace](https://scoutapm.com/devtrace)
- [Chrome Rails Panel](https://chrome.google.com/webstore/detail/railspanel/gjpfobpafnhjhbajcjgccbbdofdckggg/related)
- [A new way to understand your Rails app performance](https://www.justinweiss.com/articles/a-new-way-to-understand-your-rails-apps-performance/)



Webhooks are HTTP requests sent from an external service which ping your application at a pre-defined URL, usually with some data in tow. You then use this data in your application as needed. More often than not they are `POST` requests. They are a mainstay of the modern web. 

Webhooks are often used to keep data in sync. For example, a payment service such a Stripe sends out webhooks whenever an event happens; a new subscriber, a failed payment, etc. You then 'catch' this webhook, and use the data Stripe sends with the request to update your application. 

As with [so many things](https://jameschambers.co.uk/rails-api) in modern web app development, Rails makes receiving webhooks a breeze. That said, building webhook-based functionality locally can be challenging. There are two main sticking points:

- Webhooks come from external services, and you're working on a local machine with a variable IP address
- Testing webhooks through controllers can quickly become bloated

Without further ado, let's dive in. Note that this guide assumes you're using Rails 6 and RSpec. 

## Install ngrok for local webhook testing

First challenge – webhooks are sent from external services, whereas development environments are on a local machine without a fixed address. Pushing code to a staging server for testing is an option, but it's a very slow process. Thankfully, there's a better way. Enter, [ngrok](https://ngrok.com). 

Ngrok allows you to create a 'tunnel URL' to your local machine. This tunnel gives access a given port on your local machine from anywhere on the internet. It's ideal for working with webhooks.

The free version of ngrok gives random subdomains every time you start up. This means you'll need to change your webhook testing URLs every time you start ngrok. With the $5 / month plan you can set a custom subdomain, which bypasses this problem entirely. IMHO that's money well spent. 

Once you've [installed ngrok](https://ngrok.com/download) (and optionally set up your subdomain), it's time to fire 'er up: 

```bash
$ ~/ngrok http -hostname=YOUR_HOSTNAME.eu.ngrok.io -region=eu 3001
```

Couple of things to note here. We're running ngrok on port `3001` as our Rails server is running there. If you have a custom ngrok domain, specify it with the `-hostname` flag. Finally, you have to specify a `-region` flag if you're outside the US.

If you don't have a custom domain, just remove the `-hostname` and `-region` and you'll get a temporary URL: 

```bash
$ ~/ngrok http 3001
```

And with that, you're up and running. You also get a nifty dashboard to inspect incoming webhook requests at `localhost:4040`:

![Ngrok screenshot](https://img.jame.sc/ngrok-rails-webhook.png)

## Add your ngrok host to Rails

[Starting in Rails 6](https://www.fngtps.com/2019/rails6-blocked-host/), you must give your ngrok tunnel URL permission to access your development environment. Add the following to your `development.rb` file (remember you must restart your server after editing `development.rb` for changes to take effect).

```ruby
# config/environments/development.rb
Rails.application.configure do
	# ...
  config.hosts << 'YOUR_HOSTNAME.ngrok.io'
	# ...
end
```

## Create your webhook route

As mentioned at the top, webhooks are almost always `POST` requests. We'll create a very simple route to handle an incoming webhook in our `routes.rb` file: 

```ruby
# config/routes.rb
Rails.application.routes.draw do

	# ...
  resources :webhooks, only: :create

end
```

This gives us a `[POST localhost:3001/webhooks](http://localhost:3001/webhooks)` route, but thanks to ngrok we can *also* access that route through our custom tunnel URL,  `POST https://YOUR_HOSTNAME.ngrok.io/webhooks`. Next, let's set up our webhooks controller:  

```ruby
# app/controllers/webhooks_controller.rb
class WebhooksController < ApplicationController

  skip_before_action :verify_authenticity_token

  # POST /webhooks
	def create
  end

end
```

We skip token authenticity verification to allow our webhook request through, as Rails will automatically block any incoming HTTP POST requests out of box.

## Extract webhook logic into service objects

Test-driven development is a thing of beauty. But testing webhook functionality through controllers can quickly become bloated. Nobody wants a fat controller. 

The solution is to extract webhook parsing into service objects (a.k.a. plain old ruby objects / POROs), then test the service objects. 

Here's the skeleton of a basic webhook parsing spec/service. In a nutshell, it will parse a JSON payload, then perform a different action depending on the event `type`: 

```ruby
# app/services/webhook_parsing_service.rb
class WebhookParsingService

	attr_reader :errors

  def initialize(payload)
		@payload = payload
		@errors = []
	end

	def success?
		@errors.empty?
	end

	def call
    parse_json_payload
    filter_events if success?
    self
  end

  private

  def parse_json_payload
    @json = JSON.parse(@payload)
  rescue JSON::ParserError => e
    @errors << e.message
  end

  def filter_events
    if @json['type'] == 'some.event'
		  # ...
    elsif @json['type'] == 'other.event'
      # ...
    end
  end

end
```

```ruby
# spec/services/webhook_parsing_service.rb
require 'rails_helper'

describe WebhookParsingService do

  context 'When an invalid object is provided' do
    it 'fails' do
      expect(WebhookParsingService.new('').call.success?).to be_falsy
    end
  end

  context 'When an valid JSON object is provided' do
    before do
      @service = WebhookParsingService.new(YOUR_JSON_STRING).call
    end

    it 'succeeds' do
      expect(@service.success?).to be_truthy
    end

		# ...

  end
end
```

## Local webhooks FTW

Webhooks help you connect your application to a world of external services. Rails and ngrok help you build test-driven webhook functionality on your local machine. And seriously, go for the custom ngrok domain. It won't change your life, but it will make it that little bit easier.



_Short on time? Get the code as a [Rails template on GitHub](https://github.com/jameschambers/boring-bits-rails-api). It's a one-line install._

I love Rails. Its rich ecosystem of tried and tested functionality makes it a great choice for building backends for everything from [SaaS apps](/saas-content-marketing) to microservices.

In this post, we'll look at how to build an API-only Rails authentication system which you might connect to a client-side frontend or app. 

We'll be using Devise for Authentication, [JSON:API](https://jsonapi.org/) for API responses, and Rspec for testing. Here's the structure we're aiming for:

<figure>
  <img src='https://img.jame.sc/rails-api-flow.jpg' alt='Rails API flow chart' />
  <figcaption></figcaption>
</figure>

[Download the flow chart as a PDF](https://img.jame.sc/pdfs/rails-api-flow.pdf)

We'll create our own session and registration controller which will extend the default Devise controllers for those same actions. On successful login / signup, we return an `Authorization` header with a `Bearer TOKEN`  value. We'll use this token to authenticate subsequent requests. 

On the client-side, we will send our `Authorization: Bearer TOKEN` header when we make our API requests. Devise then authenticates our requests, either rendering the controller action or returning a `401` error as appropriate. 

## Step 1. Rails API setup

### Install Rails

Start by creating a new Rails App with the `--api` flag. This gives you a limited set of Rails features without the whole shebang you might use for a full-stack web application:

```bash
$ rails new your_app_name --api
```

### Install Devise for authentication

We'll use [Devise](https://github.com/heartcombo/devise) for user authentication. You could say it's overkill to use Devise for a relatively simple API authentication task, but it's long-standing place as the de facto Rails authentication solution is hard to argue with: 

To install Devise, add the following to your Gemfile: 

```ruby
gem 'devise'
```

Then run `bundle install`, followed by the generator: 

```bash
$ rails generate devise:install
```

Finally, run `rails db:migrate`. That will be enough to get you up and running, but check out the [Devise documentation](https://github.com/heartcombo/devise) for more options. 

### Install devise-jwt for token-based authentication with Devise

*A big thanks to Adam Mazur whose post on [installing devise-jwt](https://medium.com/@mazik.wyry/rails-5-api-jwt-setup-in-minutes-using-devise-71670fd4ed03) I'm summarising here.* 

Devise doesn't include token authentication out of the box, so we'll use the [devise-jwt gem](https://github.com/waiting-for-dev/devise-jwt). Add it to your Gemfile: 

```ruby
gem 'devise-jwt', '~> 0.7.0'
```

 `bundle install` then add a secret key in the Devise initializer. (Pro tip: you can generate secrets on the command line in Rails with `bundle exec rake secret`). This is used to generate signed JWT tokens. We also add login/logout request routes here, together with our token expiration date.

```ruby
# config/initializers/devise.rb
Devise.setup do |config|
  # ...
  config.jwt do |jwt|
    jwt.secret = ENV['DEVISE_JWT_SECRET_KEY']
		jwt.dispatch_requests = [
	    ['POST', %r{^/api/login$}]
	  ]
	  jwt.revocation_requests = [
	    ['DELETE', %r{^/api/logout$}]
	  ]
	  jwt.expiration_time = 1.day.to_i
  end
end
```

We will revoke JWT tokens using the `DenyList` strategy. This means we create a new table in our database to store expired tokens, and cross-reference tokened requests to check they are valid. Create the migration: 

```bash
$ rails generate migration CreateJwtDenylist
```

The migration creates a simple table with an indexed string column which contains the expired token, together with an `exp` DateTime column. 

```ruby
# db/migrate/xxxxx_create_jwt_denylist.rb
class CreateJwtDenylist < ActiveRecord::Migration[6.0]
  def change
    create_table :jwt_denylist do |t|
      t.string :jti, null: false
      t.datetime :expired_at, null: false
    end
    add_index :jwt_denylist, :jti
  end
end
```

Run `rails db:migrate` , then create a model to implement the revocation strategy: 

```ruby
# app/models/jwt_denylist.rb
class JwtDenylist < ApplicationRecord
  include Devise::JWT::RevocationStrategies::Denylist

  self.table_name = 'jwt_denylist'
end
```

Finally, we need to tell our User model that we're going to authenticate with JWT, and our revocation strategy:  

```ruby
# app/models/user.rb
class User < ApplicationRecord
  devise :database_authenticatable, :registerable,
		:jwt_authenticatable, jwt_revocation_strategy: JwtDenylist
end
```

### Install rack-cors to allow cross-origin requests

Rails blocks cross-origin requests out of the box. To access our API from a different URL, we need to install the `rack-cors` gem. Add it to your Gemfile:

```ruby
gem 'rack-cors'
```

Then `bundle install`. Finally, create an initializer. We allow all origins here, but you should limit origins to a whitelist of domains in production. 

```ruby
# config/initializers/rack_cors.rb
Rails.application.config.middleware.insert_before 0, Rack::Cors do
  allow do
    origins '*'
    resource '*', 
		headers: :any, 
		methods: [:get, :post, :patch, :put, :options]
  end
end
```

### Install jsonapi-rails for easy JSON:API serialisation

We'll use the [jsonapi-rails](https://github.com/jsonapi-rb/jsonapi-rails) gem to return our models as valid JSON:API objects. Add it to your Gemfile:

```ruby
gem 'jsonapi-rails'
```

Then `bundle install`.

Define the serialized version of your `User` model in the `SerializableUser` class. This tells the controller which attributes to return in a JSON:API response for a given user. We only want `email` to start with, so we'll add that as an `attribute`, and a link to `self`. 

Learn more about the [JSON:API format as a whole](https://jsonapi.org/format/#document-top-level), or the ruby-specific [jsonapi-rb gem](http://jsonapi-rb.org/guides/serialization/defining.html).

```ruby
# app/serializable/SerializableUser.rb
class SerializableUser < JSONAPI::Serializable::Resource
  type 'users'

  attributes :email

  link :self do
    @url_helpers.api_user_url(@object.id)
  end
end
```

## Step 2. RSpec test setup

### Install rspec-rails

Our tests will use RSpec. Start by adding [rspec-rails](https://github.com/rspec/rspec-rails) to the test section of your Gemfile:

```ruby
group :test do
	gem 'rspec-rails'
	#...
end
```

Then `bundle install`. Next, run the RSpec generator on the command line:  

```bash
$ rails generate rspec:install 
```

### Install factory_bot_rails for fixtures

We'll use [factory_bot_rails](https://github.com/thoughtbot/factory_bot_rails) to create fixtures to use in our tests. Add to the test section of your Gemfile: 

```ruby
group :test do
	gem 'factory_bot_rails'
	#...
end
```

Then `bundle install`. Lastly, create a simple user factory: 

```ruby
# spec/factories/users.rb
FactoryBot.define do
  factory :user do
  end
end
```

### Install faker for test data

[Faker](https://github.com/faker-ruby/faker) helps us create real-looking test data. Add to the test group in your Gemfile: 

```ruby
group :test do
	gem 'faker'
	#...
end
```

Then `bundle install`. 

### Add UserHelpers support module

To simplify creating users during our tests, we will add a couple of helper methods: 

```ruby
# spec/support/user_helpers.rb
require 'faker'
require 'factory_bot_rails'

module UserHelpers

  def create_user
    FactoryBot.create(:user, 
			email: Faker::Internet.email, 
			password: Faker::Internet.password
		)
  end

	def build_user
    FactoryBot.build(:user, 
			email: Faker::Internet.email, 
			password: Faker::Internet.password
		)
  end

end
```

*Note that `FactoryBot.create` actually creates the user in the database, whereas `FactoryBot.build` just gives us the attributes.* 

Require all support files, and include our new `UserHelpers` module in `RSpec.configure`: 

```ruby
# spec/rails_helper.rb
# ...
# Requires supporting ruby files 
Dir[Rails.root.join("spec/support/**/*.rb")].each { |f| require f }

RSpec.configure do |config|
  # ...
  config.include UserHelpers
	# ...
end
```

Now we can use `create_user` and `build_user` in our specs. 

### Install jsonapi-rspec for response matching

The [jsonapi-rspec](https://github.com/jsonapi-rb/jsonapi-rspec) gem provides some neat matchers for JSON:API responses. Add to the test group in your Gemfile: 

```ruby
group :test do
	gem 'jsonapi-rspec'
	#...
end
```

Then `bundle install`. Finally, require the gem in your rails_helper, then include it in your RSpec config. 

```ruby
# spec/rails_helper.rb
# ... 
require 'jsonapi/rspec'

RSpec.configure do |config|
	# ...
  config.include JSONAPI::RSpec
	# ...
end
```

### Add ApiHelpers support module

To complete our test set up, we'll create a support file to cut down on repetition when working with API responses: 

```ruby
#spec/support/api_helpers.rb
module ApiHelpers

  def json
    JSON.parse(response.body)
  end

  def login_with_api(user)
    post '/api/login', params: {
      user: {
        email: user.email,
        password: user.password
      }
    }
  end

end
```

As with our `UserHelper`, `ApiHelper` will be automatically `require` -d in our `rails_helper`. All we have to do is include it in `RSpec.configure`: 

```ruby
# spec/rails_helper.rb
# ...
# Requires supporting ruby files 
Dir[Rails.root.join("spec/support/**/*.rb")].each { |f| require f }

RSpec.configure do |config|
  # ...
  config.include ApiHelpers
	# ...
end
```

## Allow users to Sign Up

Now our test framework is all set up, let's start TDD-ing. We'll kick off with our routes.

All routes are prefixed with `/api`. To avoid conflicts with Devise's own namespacing logic we'll manually set our authentication routes in `path_names`. We'll also default to a json response format while we're at it. 

All other API controllers go under `namespace :api`, and are stored in `app/controllers/api/` folder. We'll just add a users#show action for now. 

```ruby
# config/routes.rb
Rails.application.routes.draw do

  namespace :api, defaults: { format: :json } do
    resources :users, only: %w[show]
  end

  devise_for :users,
    defaults: { format: :json },
    path: '',
    path_names: {
      sign_in: 'api/login',
      sign_out: 'api/logout',
      registration: 'api/signup'
    },
    controllers: {
      sessions: 'sessions',
      registrations: 'registrations'
    }
end
```

### Add a JSON:API response helper to ApplicationController

We'll use this to render JSON:API responses in our Devise controllers. 

```ruby
# app/controllers/application_controller.rb
class ApplicationController < ActionController::Base
  
  def render_jsonapi_response(resource)
    if resource.errors.empty?
      render jsonapi: resource
    else
      render jsonapi_errors: resource.errors, status: 400
    end
  end

end
```

### Create a Registration Spec

We use request specs, not controller specs. Unlike controller specs, request specs load the whole stack and return the Authorization headers which are critical to test. 

```ruby
# spec/controllers/api/registrations_controller_spec.rb
require 'rails_helper'

describe RegistrationsController, type: :request do

  let (:user) { build_user }
  let (:existing_user) { create_user }
  let (:signup_url) { '/api/signup' }

  context 'When creating a new user' do
    before do
      post signup_url, params: {
        user: {
          email: user.email,
          password: user.password
        }
      }
    end

    it 'returns 200' do
      expect(response.status).to eq(200)
    end

    it 'returns a token' do
      expect(response.headers['Authorization']).to be_present
    end

    it 'returns the user email' do
      expect(json['data']).to have_attribute(:email).with_value(user.email)
    end
  end

  context 'When an email already exists' do
    before do
      post signup_url, params: {
        user: {
          email: existing_user.email,
          password: existing_user.password
        }
      }
    end

    it 'returns 400' do
      expect(response.status).to eq(400)
    end
  end

end
```

### Create a Registrations Controller

We inherit from Devise's own Registrations controller, so not much to add here. We attempt to save the user on signup, then return our custom response with the `render_jsonapi_response` method we added in `ApplicationController` earlier on. 

```ruby
# app/controllers/registrations_controller.rb
class RegistrationsController < Devise::RegistrationsController

  def create
    build_resource(sign_up_params)
    resource.save
    sign_up(resource_name, resource) if resource.persisted?

    render_jsonapi_response(resource)
  end
end
```

Run `foreman run rake` again and you should see your tests pass. 

## Allow users to Log In & Log Out

As with our `RegistrationController`, we'll write our (failing) spec before writing the code to make it pass: 

```ruby
# spec/controllers/api/sessions_controller_spec.rb
require 'rails_helper'

describe SessionsController, type: :request do

  let (:user) { create_user }
  let (:login_url) { '/api/login' }
  let (:logout_url) { '/api/logout' }

  context 'When logging in' do
    before do
      login(user)
    end

    it 'returns a token' do
      expect(response.headers['Authorization']).to be_present
    end

    it 'returns 200' do
      expect(response.status).to eq(200)
    end
  end

  context 'When password is missing' do
    before do
      post login_url, params: {
        user: {
          email: user.email,
          password: nil
        }
      }
    end

    it 'returns 401' do
      expect(response.status).to eq(401)
    end

  end

  context 'When logging out' do
    it 'returns 204' do
      delete logout_url

      expect(response).to have_http_status(204)
    end
  end

end
```

### Create a Sessions Controller

Similarly to Registrations, we don't need to add much to the default Devise Sessions Controller. We'll send a response with the `render_jsonapi_response` method we previously added to our `ApplicationController`, and a `204` status when logging out. Other than that we're just inheriting everything from Devise. 

```ruby
# app/controllers/sessions_controller.rb
class SessionsController < Devise::SessionsController

  private

  def respond_with(resource, _opts = {})
    render_jsonapi_response(resource)
  end

  def respond_to_on_destroy
    head :no_content
  end

end
```

Again, run `foreman run rake` and you'll be off to the races. 

Congratulations. You've just set up JWT-powered authentication. Next, let's create an authenticated route which uses our new setup.

## Make an API Request

We're no longer inheriting from the Devise, so we will create a Base API controller to hold shared functionality.

As want to authorise all API requests, we use Devise's `:authenticate_user!`.  This means we will automatically authenticate all our API controller actions. Pretty neat. 

```ruby
# app/controllers/api/base_controller.rb
class Api::BaseController < ApplicationController

  before_action :authenticate_user!

  rescue_from ActiveRecord::RecordNotFound, with: :not_found

  def not_found
    render json: {
      'errors': [
        {
          'status': '404',
          'title': 'Not Found'
        }
      ]
    }, status: 404
  end

end
```

We'll add a generic 404 handler while we're at it. 

### Create a User Controller Spec

We'll use the login_with_api method from our `ApiHelpers` to log in before making each request. This ensures we set the necessary Authentication headers.

```ruby
# spec/controllers/api/users_controller_spec.rb
require 'rails_helper'

describe Api::UsersController, type: :request do

  let (:user) { create_user }

  context 'When fetching a user' do
    before do
      login_with_api(user)
      get "/api/users/#{user.id}", headers: {
        'Authorization': response.headers['Authorization']
      }
    end

    it 'returns 200' do
      expect(response.status).to eq(200)
    end

    it 'returns the user' do
      expect(json['data']).to have_id(user.id.to_s)
      expect(json['data']).to have_type('users')
    end
  end

  context 'When a user is missing' do
    before do
      login_with_api(user)
      get "/api/users/blank", headers: {
        'Authorization': response.headers['Authorization']
      }
    end

    it 'returns 404' do
      expect(response.status).to eq(404)
    end
  end

  context 'When the Authorization header is missing' do
    before do
      get "/api/users/#{user.id}"
    end

    it 'returns 401' do
      expect(response.status).to eq(401)
    end
  end

end
```

As before a `foreman run rake` will show a failing test, so let's set up the controller:

It's just connecting the dots at this point. As we authenticate API requests and handle 404s in our base controller, so all we have to do is find the user and render the JSON:API response. Easy peasy:

```ruby
# app/controllers/api/users_controller.rb
class Api::UsersController < Api::BaseController

  before_action :find_user, only: %w[show]

  def show
    render_jsonapi_response(@user)
  end

  private

  def find_user
    @user = User.find(params[:id])
  end

end
```

## Conclusion

And that's it! It takes a bit of setup, but once you've done the legwork you've got yourself a flexible, test-driven authenticated API to use on the frontend of your choice. 

Get the code in this post as a [Rails template on GitHub](https://github.com/jameschambers/boring-bits-rails-api).



![pegged-mortise-stool-outside-with-flowers](https://img.jame.sc/pegged-mortise-stool-outside-with-flowers.jpeg)

We left London in August 2019, boxed up and ready for our new life in the countryside. Among the many perks was space to assemble a small workshop in our garage. I was in the workshop more or less every day during my masters, so building my own was the realisation of a long-held dream.

Every workshop needs a stool. I ambitiously acquired a copy of Christopher Schwartz's [Anarchist's Design Book](https://lostartpress.com/products/the-anarchists-design-book) and set about building a simplified version of his bar stool. The book itself is both beautiful and practical, and if you're interested in building simple furniture or indeed the history of 'vernacular' furniture design, buy a copy.

## Part One: The Legs

The stool is assembled with [staked tenon joinery](https://blog.lostartpress.com/2015/03/11/the-staked-furniture-toolkit/). Furniture has been made like this for thousands of years. The downward force onto the joint strengthens it, so barring acts of god / drunkenness, this stool should outlive me.

I had some 18mm stock leftover from another project, so I face-glued two lengths together to get the basic dimensions for the legs. It would be simpler to glue a single length together and cut it to length rather than 5 separate glue-ups. Unfortunately, my high-street-bought stock wasn't straight enough for that.

<figure>
  <img src='https://img.jame.sc/clamping-leg-stock.jpeg' alt='clamping leg stock' />
  <figcaption>You can never have enough clamps, and I don't.</figcaption>
</figure>

You may notice there are 5 legs here, but only 3 on the finished stool. Funny story, I took Mr Schwartz's advice and made an extra leg in case of cock-ups, but for some reason thought the final stool needed 4 legs, not 3. Either way, I didn't make any unrecoverable mistakes and didn't need the spare(s) in the end.

<figure>
  <img src='https://img.jame.sc/leg-stock-ripped.jpeg' alt='leg stock ripped' />
  <figcaption>Leg stock ripped to width on the table saw</figcaption>
</figure>

With the legs ripped to their outer dimensions on the table saw, it's time to make them octagonal.

<figure>
  <img src='https://img.jame.sc/marking-octagonal-legs.jpeg' alt='marking octagonal legs' />
  <figcaption>Marking the octagonal legs</figcaption>
</figure>

I started out using a compass to mark the octagonal profile for the legs, but quickly realised I'm not that accurate with a hand plane. I ended up marking out the profiles with a 6-inch ruler. This proved more than adequate - turns out the eye is quite forgiving in the final judgement.

<figure>
  <img src='https://img.jame.sc/planing-octagons.jpeg' alt='planing octagons' />
  <figcaption>Planing the octagonal legs using the workmate</figcaption>
</figure>

The fitted workbench in my garage didn't have the work-holding capacity for planing the octagonal leg profiles. Enter the ever-industrious black labrador of every British workshop - the black and decker workmate. It was the perfect tool for the job. The groove on the internal edges is ideal for holding legs.

<figure>
  <img src='https://img.jame.sc/post-plane-octagons.jpeg' alt='post-plane-octagons' />
  <figcaption>Plane to the line, and you've got an octagon</figcaption>
</figure>

## Part Two: The Seat

The seat is two pieces of 2x4 edge joined with standard wood glue. Not pictured is the moment the seat fell apart after I'd jointed the two boards to make the main seat body. Another round of glueing and all was well.

<figure>
  <img src='https://img.jame.sc/drilling-leg-mortise.jpeg' alt='drilling-leg-mortise' />
  <figcaption>Drilling the leg mortises</figcaption>
</figure>

The seat is clamped to a 'Banjo jig', which is just a piece of MDF and a hinge set to 15 degrees. My only gripe with this setup is the leg position is limited by the throat depth on the pillar drill. Long-term I think this needs to be a hand-drill operation.

<figure>
  <img src='https://img.jame.sc/reaming-leg-mortise.jpeg' alt='reaming-leg-mortise.jpeg)' />
  <figcaption>Shaping the leg mortises with a reamer</figcaption>
</figure>

After drilling the initial holes with a Forstner bit I switched to the reamer. A reamer makes a cone out of an existing hole, which will hold the conical ends of the legs.

## Part Three: Assembly

I neglected to document the final step of the leg build. You use an oversized pencil sharpener (a.k.a. a tenon cutter) to turn the end of the leg into a big pencil shape. It's the exact opposite shape to the reamer, so one fits the other nicely.

<figure>
  <img src='https://img.jame.sc/pre-assembly.jpeg' alt='pre-assembly' />
  <figcaption>Seat and legs, post reaming</figcaption>
</figure>

I cut the corners off the rear of the seat and used the hand plane to add a 45-degree bevel on the underside.

The tenons are secured by splitting them with a chisel, then glueing in a piece of hardwood (oak, in my case). This runs across the grain of the seat to prevent splitting.

<figure>
  <img src='https://img.jame.sc/before-trimming.jpeg' alt='before-trimming' />
  <figcaption>Test-fitting the legs</figcaption>
</figure>

With the glue dry I trimmed the tenons flush with the seat using a hand saw, then sanded down the whole thing with some 220 grit sandpaper.

This won't get a lot of heavy use, so I applied a shellac sanding sealer then a coat of clear paste wax for a bit of sheen.

<figure>
  <img src='https://img.jame.sc/marking-legs.jpeg' alt='marking-legs' />
  <figcaption>Marking where to cut the legs</figcaption>
</figure>

I cut the legs level by placing offcuts under each leg until the top was parallel, then tracing around the legs with a pencil taped to another offcut. Simple and effective.

## The finished product

![pegged-mortise-stool-outside-with-flowers](https://img.jame.sc/pegged-mortise-stool-outside-with-flowers.jpeg)

I've made three split-mortise benches since this bar stool. They're simple, strong, and they look good, even when things don't turn out perfectly. I'm a fan.



Writing is important to me. But try as I might, I always seem to let my long-term writing habit slip. So, I'm trying something new; I'm setting myself the goal of publishing 250 pieces of content by the end of 2020. I'm tracking this goal with coffee beans.

![No beans](https://img.jame.sc/190427-000-1.jpg)

The bottle on the left contains 250 coffee beans (it looks like less but trust me, I counted). The bottle on the right contains none. Each time I publish a piece of content, I'll move a bean from 'to do' to 'done'. I'll keep doing this until 'to do' is empty.

## Why not just use a checklist?

I'm interested in using visual cues to help ingrain my writing habit. The idea is stolen pretty much wholesale from James Clear's post on [building habits with paper clips](https://jamesclear.com/paper-clips). The premise is that visual cues are one the best ways to encourage habit formation; if you're looking at something, it's much harder to ignore it. My previous habit tracking has been almost exclusively digital, so I'm interested to see whether a physical approach will yield better results, particularly long-term.

## What counts as 'content'?

Anything online I've had a significant part in creating which is accessible via its own URL on a platform I can control. Blog posts, newsletters, and process guides count. Tweets, Instagram updates, and Boords features don't.

Only promoted content is considered 'done'. Promotion has been a weakness for me in the past. Just publishing something on my blog and leaving it at that isn't going to cut it. I have to tweet about it, tell my mailing list, etc.

## Why are you publishing this?

I think making this public will keep me accountable. Social accountability (i.e. not wanting to look like a jackass) kept me going through the early days of [my newsletter](https://innerjoiner.com/), when subscribers were hard to come by, and praise harder still. I'm hoping the same will be true here.

## Why 250? And why coffee beans?

Coffee beans look nice and, for now, smell nice too. As for 250, I wanted a round number, and that's how many beans fit into the bottle. ¯\_(ツ)_/¯

## How will you be updating this?

On [Twitter](https://twitter.com/jameschambers). Every time I publish something, I'll post the URL, together with a picture of the bottles. I'm not much of a tweeter otherwise, so I'm hoping the photographs will form a sort of project timeline.

## One down

![One bean](https://img.jame.sc/190427-001-1.jpg)

With a satisfying clatter, the first bean has made the leap. Only 249 to go.



<figure>
  <img src='https://img.jame.sc/crowe.jpeg' alt='Crowe' />
  <figcaption>Illustration by Frida Ek (Animade)</figcaption>
</figure>

Six years into running Animade, we permanently removed two-thirds of the projects from our website. But why did we need to do something so drastic?

Electric shocks defined my first year at college. I plunged headlong into a world of Arduino, poorly soldered circuit boards, and even more poorly insulated power supplies. Each month brought a new project, and survival depended on the ability to switch disciplines at a moments notice. I loved it.

In 2010, Tom and I started Chambers Judd, later to become Animade. It was (and is) a good partnership. Having known each other since primary school, we could be confident the other one wasn't going to run off with the petty cash tin. Plus, our skills overlapped, and we shared a willingness to take a run at most projects.

This willingness - combined (at least on my part) with a very real fear of losing everything and having to move back in with my parents - led to a liberal approach to our early project selection process. Web development, presentation decks, and banner ads were all fair game. Creating a coherent body of work came second to keeping the lights on.

### The tangle

This worked well, until it didn’t. With each new project, our portfolio felt more confused. You'd find web development next to an explainer video; a healthcare iPad app next to stop-motion animation. Like headphones in a jacket pocket, our work became difficult - some might even say annoying - to untangle.

There is a fine line between 'interdisciplinary' and 'unrelated'. Our brains are wired to look for patterns, and showing a bunch of disparate projects next to one another can have the side-effect of making them all look worse. This project jumble made our portfolio appear less than the sum of its parts.

Client presentations made this particularly clear. We'd be talking through a Keynote deck, and as we flitted around between projects, we'd often see a collective furrow of the audience's brow. Most wouldn't say anything, but they didn't need to; we'd lost them. We could talk about our work until the cows came home, but they'd still be trying to figure out what an editorial website had to do with an explainer video (answer: nothing).

Negative effects started showing up inside the company, too. Our project managers ran twelve-month web development projects alongside two-week animation projects; two very different processes. Keeping the plates of project management spinning is hard enough without adding a salad bowl into the mix.

### The trim

We needed clarity, so set about pruning our portfolio. Character animation is Animade's sweet spot: it's what we do best, and where we provide the greatest value to our clients. We trimmed our portfolio to include projects related to that core offering, leaving about a third of them. This left two-thirds of our portfolio on the scrap heap.

This was a wrench. Confusing or not, six years is enough time to develop a significant emotional attachment to your work. And emotions aside, could we be setting ourselves up for financial disaster?

Turning away work - as anyone running a small business knows - is utterly terrifying. But the benefits of our newfound clarity are undeniable. Our production process is significantly simpler. Presenting our work is an opportunity to reinforce what we stand for, not explain what it all means. We’ve built a platform for the next stage in the life of our studio, and it’s built on our strengths.

Attention is scarce. Offering too many services - while seemingly providing a convenient safety net - dilutes your portfolio. Over time, it becomes confusing. Find your sweet spot, then trim like there’s no tomorrow.

*This post was originally published on the [Boords Blog](https://boords.com/blog/why-we-deleted-two-thirds-of-our-portfolio).*



London is not a city built for snow.

Those who were here during the winter of 2010 may remember the 12 inches of the stuff which fell in the space of one eventful December afternoon. That day the city ground to a cold, damp, although admittedly aesthetically appealing, halt.

That was also the day my business partner Tom and I were fitting desks in our first office. That office would later become home to [Animade](https://animade.tv/). But at the time, I had more pressing concerns. Trying to get a sheet of plywood through a door and up some stairs in a blizzard is not an experience I would recommend.

Overall though, it was a hugely exciting time. Work was coming in, and we were saying yes to everything. Because that's what you do when you're starting out. Just say yes, and find a way. We didn't see losing a couple of days to desk-building as a problem - we'd just make up the time somewhere else. Weekends, evenings, whenever.

But, of course, you can't keep saying yes indefinitely. Eventually, we spread ourselves too thinly, for too long. As the only people at the company, we were doing everything. Desk building, project management, bookkeeping, and of course the creative work we were hired for.

Soon enough, the cracks started to show. Deadlines were missed, grovelling apologies were made. The work began to suffer, and we had to act. If we wanted to take on more work, we needed to bring on more staff. We had no business or management training. Where to start?

There are a lot of pitfalls involved in bringing people into a business you've started yourself. However, with a bit of effort in the right places, the process can be much, much simpler than we made it.

## Start at the end

One way of solidifying your goals if you're growing a business is to consider the size and makeup you'd like your company to have for it to be "done". How many people will work there? What job titles will they have?

List out who will work in the dream version of your company, together with a summary of what they're accountable for. Underneath that, write who is currently responsible for each role.

If you're working on your own, it'll look something like this:

<img src='https://img.jame.sc/you.png' alt='You' />

It might seem silly to do this if you're a one-person outfit, but being honest about the work on your plate is incredibly valuable for your own sanity as much as anything else. There's so much which goes into running a company, but a lot of it can go assumed or unsaid. Getting a picture of everything which needs to happen to get a business to function is a vital step.

## Sharing the load

With your ideal company structure in hand, you'll have a map of the road ahead. For the sake of argument, let's say you bring on some part-time project management help.

Now, your company structure looks like this:

<img src='https://img.jame.sc/not-you.png' alt='Not You' />

Wonderful! But there's a problem. How will the person you bring in know how you'd like things to run in a way that's unique to you?

In short, they won't.

For a long time, we were keeping the knowledge of how our company ran (or how we wanted it to) in own heads. If it wasn't in our brains, it was on post-its, in random text files, or scrawled on the back of beer mats. It's not easy for someone new to take that information and run with it.

The solution: Playbooks.

## The beauty (and pain) of writing everything down

The key to being in a position to bring on help is to write down how to do things. It sounds simple, and it is. The discipline is in making it a habit and keeping that information up to date (that's the "pain" part).

These are your Playbooks. They outline how your company works in the way that you want it. How *you* do things. In detail.

For example, sharing images on social media involves exporting files at various resolutions and sizes. Sure, you can Google these each time you want to post work online. But if you want someone else to help you, you've got to rely on them to search for that information each time. Putting that information in a Playbook means there's one place to look, and a clear, repeatable process, regardless of who is doing it.

## Marketing playbook sample

To give a sense of how we approach Playbooks I've collected together a couple of sections from the Marketing Playbook we use at Animade. Of course, this barely scratches the surface of everything the role entails. Nonetheless, it will give you an idea of how we like to document things.

Generally speaking, the content of a given Playbook isn't groundbreaking, and this sample is no exception. But the benefits of having a centralised place for practical things like this are immense. Sometimes half the battle with small admin tasks can be remembering where you bookmarked the information you need. Playbooks take that mental fuzz totally out of the equation.

## Applying this to your company

We have a Google Doc Playbook for each role, but starting off with one for everything will work well as a first step. We've found Google Docs to be perfect because everyone knows how they work, they're collaborative, and it's super easy to paste screenshots in.

Even if you never plan to hire people or grow beyond a one-person outfit, I believe this is a robust approach to running a creative company. Acknowledging everything that goes into keeping a business running is crucial, regardless of your goals.

If you're interested in learning more, I'd highly recommend taking a look at [The E-Myth Revisited](https://www.google.co.uk/url?sa=t&rct=j&q=&esrc=s&source=web&cd=3&ved=0ahUKEwiX-vnxypDXAhWFVRoKHUklC_QQFghTMAI&url=https://www.amazon.com/Myth-Most-Businesses-Dont-About/dp/0887303625&usg=AOvVaw1Nx_IedSvhg7lNdmfa_1tl). It changed the way I thought about running a company.



If you need to quickly resize a bunch of images on a Mac, you don't need to open Photoshop. There's a simple way to do it from the command line, by using the `sips` command. This is the basic syntax:

## Resize a single image

By way of example, to resize a single image to a maximum of 800px (either width or height), you'd use the following. It's important to note that this will **replace the existing image**, so make a copy if you want to keep the original.

```bash
$ sips -Z 800 image.jpg
```

## Resize multiple images

Where `sips` really comes into it's own is for folders of images. To resize multiple images just use a wildcard `` with the file extension (`.jpg` in this case). The example below will blast through all the images in `folderName`, resizing them to 1200px in a flash.

```bash
$ sips -Z 1200 folderName/*.jpg
```

## Resize multiple images with format conversion

Converting the format of the image along with resizing is best done through imagemagick's `mogrify` command. First, ensure you have imagemagick installed:

```bash
$ brew install imagemagick
```

Then run `mogrify` . The following command will resize all images from `inputFolder` to 800px wide jpgs in `outputFolder`. 

```bash
$ mogrify -resize 800 -path 'outputFolder/' "inputFolder/*.jpg"
```

The full list of mogrify options [is available here](https://imagemagick.org/script/mogrify.php).



I don't go anywhere near the majority of what Git can do. Nevertheless, over the years I've arrived at a workflow which seems to have stuck. It's by no means revolutionary, but it gets the job done.

About half the time I use Git on projects only I will ever see, and the rest of the time I work collaboratively with a handful of people in my team. This workflow is heavily influenced by the concepts covered in the [Git course on Upcase](https://thoughtbot.com/upcase/videos/git-workflow). If you're looking to improve your skills as a developer, check it out.

This is what the workflow looks like:

- Check out a new branch
- Work on that branch, making several commits
- Merge changes back into the master branch in a single, curated commit

The idea is that a single large commit keeps the master branch neater than lots of small commits. Let's go through each step in more detail.

## The cheatsheet

![Git workflow](https://img.jame.sc/git-workflow.gif)

### Step 1: Create a new branch to work on

```bash
# Create a new feature branch
git branch jc_new_feature
# Checkout your new feature branch
git checkout jc_new_feature
```

It's good practice to start feature branch names with your initials, then a description of the feature itself (e.g. `jc_feature_name`). This helps others working on a project to see who's been doing what.

### Step 2: Write code, commit regularly

```bash
# Add all files to the stage
git add .
# Commit files 
git commit -m "Description of this commit"
# Optional (but recommended) push local branch to remote
git push origin jc_feature_name
```

Commit regularly. I've never regretted making a commit, but have regretted not making one. You'll have a chance to change your commit messages before merging back into master.

### Step 3: Fetch when you're done

When you're ready to merge your features back into the master branch, run `git fetch`.

```bash
git fetch
```

Fetching makes sure you're up to date when merging changes back into master. This doesn't actually merge the code with the code on your machine (git pull does that), but rather updates references to any remote changes which may have happened while you've been working locally. It's the groundwork for the next stage.

### Step 4: Squash your commits and get ready to merge

Next, you'll rebase your changes into the master branch. This effectively condenses down all your feature branch commits (`jc_feature_name`) into a single commit. We'll merge this single commit back into the `master` branch.

```bash
# Open the interactive rebase tool
git rebase -i origin/master
```

This will open an interactive rebase tool, which shows all the commits you've made on your branch. You'll then "squash" all your changes into one commit.

```bash
# Interactive rebase tool
pick bf27dcd Initial change
pick cc570e1 Second change
pick ca0ec55 Third change
```

Squash your commits by replacing pick with s for all but the top commit. s is shorthand for squash - imagine all the changes you've made being "squashed" up into the top commit.

```bash
# 'Squashing' the second and third commit into the first
pick bf27dcd Initial change
s cc570e1 Second change
s ca0ec55 Third change
```

When you close this window you'll see all your existing commits, which you can edit to be more concise. Exit the rebase tool and you're ready to merge.

### Step 5: Merge your changes

Prepare to merge your changes by switching to the master branch. Remember that you're merging changes *into* the branch you're currently on.

```bash
# Checkout the master branch
git checkout master
# Merge jc_feature_name INTO master
git merge jc_feature_name
```

The changes from the `jc_feature_name` branch are now merged into your `master` branch. Happy days. Now's a good time to push your changes to the remote master branch.

```bash
# Push your local master branch to remote 
git push origin master
```

### Step 6: Cleanup

With your changes merged into the master branch, you can safely delete your feature branches.

```bash
# Delete remote feature branch (the colon is important!)
git push origin :jc_feature_name
# Delete local branch
git branch -d jc_feature_name

```

And with that, you're done.

## Making it work

It's easy to feel insecure about using Git. The spectre of lost work looms large. The key to making this system work is to go through the process a lot, regularly branching and merging. This gets you comfortable with the workflow and has the added bonus of ensuring one branch never gets too far out of line with another.



Dear me,

I get it. You know how to use Sublime and like to think you're pretty good with it. You've got enough on your plate without learning a 20 year old text editor which is going to slow you down for a while. There are deadlines to think of.

I hear you James. Really, I do. But here's why you're wrong:

1. You'll be much, much more efficient than in Sublime
2. This will make you better at your job
3. There's loads of great plugins
4. It's totally themeable and can be made to look awesome
5. It's full of amazing little tricks to help you with laborious things
6. You'll become a better typist
7. It's the last text editor you'll ever have to learn

<figure>
  <img src='https://img.jame.sc/vim-screenshot.gif' alt='Vim screenshot' />
  <figcaption>Screenshot of Vim being awesome</figcaption>
</figure>

That said, there are a few things you should know before you start.

1. If you can afford to, use the [upcase.com](http://upcase.com/) tutorials to learn. They're video based and awesome. If you can't just use vimtutor and practice.
2. You need to delete Sublime and just use Vim. It's the only way.
3. Use iTerm2
4. It will be incredibly slow and incredibly annoying for the first day or so
5. It will be quite slow and quite annoying for another 2 weeks
6. It will be amazing from then on
7. Learn tmux (also through upcase) shortly after Vim. It makes terminal/iterm much faster to work with.

There are a few Vim plugins which will make life easier (install them with [Pathogen](https://github.com/tpope/vim-pathogen)). None of them are absolutley critical, mind you neither is central heating but I think we can all agree it's a pretty good idea.

- [NERDTree](http://vimawesome.com/plugin/nerdtree-red) – a directory browser
- [CTRL-P](http://vimawesome.com/plugin/ctrlp-vim-red) – fuzzy file finder
- [AirLine](http://vimawesome.com/plugin/vim-airline) – Status bar
- [Commentary](http://vimawesome.com/plugin/commentary-vim) – Fast comments
- [Surround](http://vimawesome.com/plugin/surround-vim) – Quickly quote
- [iTerm2 Spacedust theme](https://github.com/mbadolato/iTerm2-Color-Schemes#spacedust) – Kickass iTerm2 theme

Bottom line, it's worth your time to learn Vim. I promise you.

Yours sincerely,  

Future You



A couple of months ago I released [FeedHop](http://feedhop.io/?rel=jc), a minimal web-based newsreader. Now that I've got a bit of distance from it, it feels like a good time to reflect back on what I've learned and things I'd do differently.

### 1. Don't start by nerding out

If your goal is to build something people want to use, I believe it's important to start with a problem you want to solve, not a technology you think might be interesting.

In my case, the problem I identified was partly to do with bloated RSS readers, but mostly to do with me wanting to try out some new technology (in this case React & Flux). While fun, this is not a good enough reason for a digital product to exist. A personal project, sure, but a product… no. It took a lot of time and feedback from some very generous people to begin to shape it into something which is of use, and I hope by iterating on it it'll become more useful still. Were I to start again, this rationale would be hammered out in a good deal more detail before one line of code was written.

That said, React & Flux are a bloody excellent combination. If you're in the business of building web apps, you should give them a try.

### 2. Install intercom

[Intercom](http://intercom.io/) lets you see how people are using your site, directly message them and send automatic emails if people have been inactive for a certain amount of time. They're not giving it away (plans start at around $50 a month) but the insight you can get from it is more than worth the price tag.

### 3. Focus on the stats that matter

Prior to launching I'd been reading the oft-quoted book "The Lean Startup" by Eric Reis, which extols the benefits of not focusing on "Vanity Metrics" (e.g. total users, page views etc.) but on "Growth Metrics" (i.e. how well the site is growing from month to month). The thinking is that if the userbase is growing, everything else takes care of itself.

When I launched I had set up tracking for about 8 of what I considered to be "Growth Metrics" but in reality I only really look at 2 of those. The first shows many people have used the site in the last 24 hours, the second how many have used it in the last month. These are known as Daily Active Users vs Monthly Active Users (DAU vs MAU). If this ratio goes up, people are joining the site. If it goes down, people are leaving. Simple, and easy to keep an eye on.

### 4. Be prepared to rewrite

FeedHop parses RSS feeds from third party sites, then stores the items from that feed in a database. Initially, I was pulling in a new copy of each feed item for every person who was subscribed to it. This was a spectacularly bad idea and quickly led to a pretty massive database. After a week, I rewrote it to pull in one central copy of a feed item and only store whether people had read/saved that item or not, slashing the database size. Moral of the story - you can try and predict this stuff up front but you'll miss things. Be prepared to rewrite on the fly.

### 5. Be realistic about post-launch

If you're bootstrapping and there isn't a direct source of revenue for your project, the chances are you won't be able to dedicate a lot of time to it after launch. Also if it's one of a few side projects you've got going on your product will only exacerbate the problem. Be honest with yourself. If you haven't bet the farm on your project it's unlikely you'll find the same drive to keep improving as you did when pushing for launch.

### 6. Set up some passive advertising

The best way to learn how to improve a product is to get a constant stream of new people coming to it and test out new features to see if they improve stickiness. This is often easier said than done, particularly after any initial hubbub around the launch of your product has died down. I was fortunate in that I've got access to an audience of (hopefully) interested people via [Hover States](http://hoverstat.es/). It took me a good month to realise that I could put an ad on Hover States for FeedHop and people might click it. However, since it was up I've had a steady stream of new users every day. Being able to do this obviously depends on the outlets you have available to you, but have a think about what other means of getting the message out on an ongoing basis you might have.



When [Tom](http://tomjudd.co/) and I started Chambers Judd (as the company was then known), we were effectively two freelancers sat in a room. Over time more people came, the [company name changed](http://animade.tv/) and as I write we’re up to 15 people and we sit in a nicer room. Looking back on the last 4 years it’s astonishing to think how we ran things in the beginning, and the pain we could have saved ourselves had we done a couple of things differently. So to that end I’ve compiled a list of blunders and subsequent lessons learned.

### 1. Not focusing our time on the skills people hired us for

In a scenario I’m sure is familiar to many, I remember when a typical workday consisted of putting together a couple of estimates, going to a new business meeting, following up on various bits and pieces over email and then realising I had 2 hours left to produce a day’s worth of creative work. Good creative work. And of course I was exhausted from all that other stuff.

If you’re being hired as a creative and spend most of your time doing non-creative stuff, you're stitching everyone up, yourself included. If you're getting work, then there's a reason you're getting it. Focus on that reason, and if you’re a creative, make that the priority. Split your time into dedicated creative and production chunks and make sure creative gets done first. You’ll be happier because you’ll do more of what you love, and your clients will be happier because you’re doing more of what they paid for.

### 2. Doing everything as soon as people ask

I’ll caveat this by saying if you have skills people need, it is of course important to use them in the most helpful way you can. And inevitably when a project launches there are tweaks and adjustments to be made as it gets out into the wild. It’s just the way it is.

There is a balance to be struck between being helpful and overworking yourself. It’s an art. I’ve found that if you instantly stop what you’re doing and carry out each request as it happens your day can very quickly fill up with bits and bobs without getting a good run of time on anything. Yes, some emails with the subject line “URGENT!!!” truly are urgent, but in reality they are few and far between. Know the difference between urgent and important, and try to gather small tasks and favours as they come in during the day. Then you’ll be able burn through them in one big lump once the genuinely important work is done.

### 3. Not knowing what cashflow was

This was possibly our biggest blunder. For a surprising amount of time Tom and I didn't actually know with any real certainty how long we could keep going with the money we had in the bank. We just winged it job to job, safe in the knowledge that bigger numbers were generally better than small er. We were lucky and this worked for a while, probably longer than it should have. There were two of us and fairly predictable overheads so we got away with it.

However one cold November morning in 2010 when we finally sat down and put together a spreadsheet, we realised things weren’t quite as we’d like them. It emerged that in about 4 weeks we wouldn’t have enough money in the bank to keep going, and those 4 weeks fell over Christmas (i.e. when no-one is commissioning new work). Huh.

In the end, we scraped together some small jobs here and there, and we got through it. But if we hadn’t sat down and gone through the figures when we did, I wouldn’t be sat here writing this today.

Get an accountant. Or at the very least a spreadsheet.

---

Part of all this was just the rough and tumble of starting up. It’s easy to pick holes with the benefit of hindsight. But we certainly could have made life easier for ourselves if we’d gotten into some good habits a little earlier on.



What if products could protect themselves from threats in their environment the way animals do in nature? Would we take better care of them? Would they last longer? Would we feel sorry for them?

I built these products during my Masters in Design Interactions at the Royal College of Art. They were exhibited at the 2011 [Talk to Me exhibition](https://www.moma.org/interactives/exhibitions/2011/talktome/objects/146367/) at the Museum of Modern Art in New York.

## Prototype 1. The Gesundheit Radio

<iframe src="https://player.vimeo.com/video/12768333?title=0&byline=0&portrait=0" width="640" height="360" frameborder="0" allow="autoplay; fullscreen; picture-in-picture" allowfullscreen></iframe>

A radio sits on a shelf, gathering dust. If it goes unused for a long period of time, the dust can ultimately cause it to stop working. The Gesundheit Radio solves this problem by periodically cleaning itself out with a mechanical 'sneeze' (the sneeze can also be trigger manually).

To my great delight the Gesundheit Radio has it's own [Wikipedia page](https://en.wikipedia.org/wiki/Gesundheit_radio).

## Prototype 2. Floppy Legs Disk Drive

<iframe src="https://player.vimeo.com/video/12767988?title=0&byline=0&portrait=0" width="640" height="360" frameborder="0" allow="autoplay; fullscreen; picture-in-picture" allowfullscreen></iframe>

Portable hard drives are vulnerable to desktop spills. Floppy Legs has a set of moisture triggered legs embedded within its body. If it senses liquid nearby it will quickly 'stand up', distancing itself from the threat. This gives the owner time to move the hard drive away from the liquid, out of danger. When the coast is clear the device gently lowers itself back down.

## Prototype 3. AntiTouch Lamp

<iframe src="https://player.vimeo.com/video/12767928?title=0&byline=0&portrait=0" width="640" height="360" frameborder="0" allow="autoplay; fullscreen; picture-in-picture" allowfullscreen></iframe>

It's not a good idea to touch a Halogen bulb. a) They're extremely hot, and b) touching them with bare hands dramatically shortens their lifespan. A motion detector in the base of the Antitouch lamp hopes to address this. When it detects someone nearby it sways away from them to avoid being touched.


Now

Writing

Projects