Since I read some articles from the Phoenix Architecture blog by Chad Fowler, I’ve been eager to try an implementation of this harness architecture as it seems to structure well what’s been going around in terms of automating the part that AI should handle versus humans in the new abstraction that LLM bring to the software engineering cycle. Naturally I started by working with Claude to ask it to read the whole blog and generate the corresponding tooling to run an agentic SDLC using these principles/architecture. Once the tool was generated with subcommands matching the various layers/steps of the workflow, I started a test project to test it.

The first part was using Claude to write specifications for the first feature: username/password authentication. I picked a typical feature to see how things would go. The generic phx (phoenix) tool was initially built to abstract which LLM tool is used and when I started to use it with Claude code (vs Claude API), it started bringing some permission issues.

One of the first issue to tackle after initial generation on this authentication cell, was the code layout. Without any constraint, Claude generated everything in one file: python, html, etc. So back to the drawing board on the phoenix tool, I figured out a way to provide conventions for the AI to use during generation, these conventions are shared by all cells and each cell generation records the hash of the convention it used so we have a way to check the convention used for a given cell generation.

After writing specs and corresponding tests as well as a CONVENTIONS.md containing the code architecture constraints, phx started generating a satisfying codebase. I had to specify that I wanted end to end tests including the UI so that the tests include more than rendering testing for the web UI. In a first pass the spec.md file of the cell also included basic specs of the REST endpoints. I modified the tool to externalize these in an OpenApi file. The tests were now using the OpenApi specs along with the other tests and results looked good.

I then created a cell to handle the infrastructure needed to run the service end to end. The first pass includes only the local runtime based on docker. Generating that cell provided a successful local environment. I want to use the same cell to generate actual AWS infrastructure that is compliant with our infrastructure as code rules. Since I already have a Claude skill that can do that, I went back to phx tooling design and modified it to be able to inject skills in the toolchain. Doing that I decided to make the phx tool a bit specialized for Claude code, at least for now. There is now also a skill that embed the code architecture constraints and replaces the CONVENTIONS.md file of the first pass.

Reference: The Phoenix Arhcitecture