Writing code with Amazon Q CLI and Zed

I read a lot, and always have a couple of books on the go at any one time (currently Linchpin by Seth Godin and The Prisoner of Heaven by Carlos Ruiz Zafon. I am always on the lookout for a new book though, and this thread on LinkedIn sparked an idea (check the comments) about building a simple book sharing application that a group of friends might use to share good books they recommend. I had an idea of what I wanted to create: a simple web application that a group of friends could use to create lists of the books they are reading, provide ratings and comments, and then allow them to share and borrow books they might be interested in.

I had a couple of hours whilst I was travelling, and wanted to use Amazon Q CLI to build this. Why? I have been slowly switching from VSCode to Zed, and there is no Amazon Q Developer plugin for Zed. I can however, use Amazon Q CLI in the terminal, so this felt like an experiment worth trying to see how I got on with this setup.

Building from a strong foundation

When I start a greenfield project, I take some time to think about the data model. I have found that this helps shape the output from AI Coding Assistants, providing more consistency and a greater alignment to what I want. This is the prompt I start off with to help shape my idea for a book sharing application.

Generate data model for a Book Sharing application that meets the following criteria:

• A user must have an invite code when they register
• Users register accounts via email address
• When a user registers it generates a new invite code for that account
• The number of users registered from any given invite code is stored with the user profile
• Users can define an alias (that does not need to be unique) and an optional bio
• Users will create a new book definition
• A book definition will have a title and author (mandatory, not unique)
• A book definition will be owned by the person creating the book definition
• A book definition will have an ISBN and link to where the book can be purchased (URL)
• A book definition will allow a number of comments to be added by anyone
• A book definition will define a recommendation for this book, which will be a sliding scale of 1 (not recommended) to 5 (highly recommended)
• A book definition will show whether the book is available to borrow (the borrow status) which will be either available or not available
• A book definition will show who has borrowed a book (it will record their alias)

Define the data model in yaml format that will work across different SQL versions

Amazon Q CLI did a decent job of creating an initial data model that I can use to bootstrap the building of the application. As I build the code up, this data model will change - there are things that I did not think of which needed to be added (for example, the ability to hide books you might not want to see, or set different categories). That is ok though, as these smaller incremental changes can be managed as long as you have the right building blocks. That is the perfect segway into looking at building blocks, or scaffolds.

Scaffolding

Scaffolds are markdown documents that live in your project workspace that provide essential context to help your AI Coding Assistants. In my experience, they do a good job at steering the direction of Amazon Q CLI. Amazon Q Developer in the IDE allows you to configure "Rules" files, which are markdown documents that live in a specific directory where you can define these scaffolding rules.

You can use the same rules files if you have been using these in Amazon Q Developer, or you can specify them in another file (for example, AmazonQ.md). I created an ".amazonq/rules" directory in my project workspace, and added two files which contain my specific preferences I want Amazon Q CLI to follow.

├── .amazonq
│   └── rules
│       ├── 1.project-layout-rules.md
│       └── 2.project-spec.md

We can check that Amazon Q CLI can see these by using the /context command.

> /context show

🌍 global:
    .amazonq/rules/**/*.md (2 matches)
    README.md
    AmazonQ.md

👤 profile (default):
    <none>

2 matched files in use:
🌍 /Users/ricsue/amazon-q-developer/book-sharing-app/.amazonq/rules/1.project-layout-rules.md (~60 tkns)
🌍 /Users/ricsue/amazon-q-developer/book-sharing-app/.amazonq/rules/2.project-spec.md (~80 tkns)

Total: ~140 tokens

The contents of these are what I have typically used, but am now beginning to split them out. (you can check out the content by looking at the repo)

The prompt

This is the prompt I spent some time (using Amazon Q CLI to help review and refine it)

Build a book sharing application that:

• Provides a Dashboard that lists the current books available
• this should be public and not require a login
• Allows a User to Register or Login to the application
• The Registration screen requires an Invite Code to allow registration to complete
• The book sharing application should have a Profile for each User
• The book sharing application should allow Users to create a new Book Definition they want to share, following the requirements for the data model
• The book sharing application should allow Users to comment on Books
• The book sharing application should allow Users to upvote any given Book
• The book sharing application should allow Users to request borrowing a book, which should notify the owner of the Book and allow them to approve or deny.

The data model for the application is in book-share.yaml

After about ten minutes, I had the outline of a working application which had all the functionality that I had requested. After spending about five minutes testing out all the features, I was officially super impressed (again).

This was just the start however, as I always like to use Amazon Q Developer to help build the core of the application, and then iterate and add new features, or perhaps make changes that I had not considered. I find that as I use AI Coding Assistants more and more, that this has led to me developing a flow that seems to work for me - it creates reliable and accurate results that do what I want.

Development flow

With the initial application up and running, I began looking at what I wanted to change, and then formulating how I was going to use Amazon Q CLI to help me make those changes. The pattern kind of looked like this:

1. Identify a change (new feature, update to existing functionality)
2. Generate a prompt, and ask Amazon Q CLI to implement the code
3. Test the new code, but also do regression testing to make sure that the previous bits of the application still worked
4. Rinse, repeat

The key to (1) is to make sure that you break down the tasks into small enough activities that are bounded with enough context. What I mean by that is that Amazon Q CLI would have enough context size (200K) to do what it needed to do. Giving it a single task is something I have found leads to more consistently good outputs, and where I asked it to fix a number of tasks I got variable results. I reviewed (2) to make sure that I stuck to this goal of having a single task.

I had a surprising insight whilst doing (3) which I have seen and mentioned in previous blog posts. The importance of testing cannot be understated, with Amazon Q CLI happy to make significant changes to the code that often mean that there are breaking changes. For example, with one task (that was implemented correctly, I suddenly lost the ability to accept book borrowing requests). For simple applications like this, doing end to end tests, does not take that long. As the code base gets bigger and more complex, I can use end user testing becoming a critical need (beyond unit and integration testing). I have not looked at this yet, but am thinking that with Amazon Nova Act there might be a good solution.

From the core of the application, I made the following iterative changes:

• Displaying books that are available (i.e. not borrowed) and all books
• Allowing someone who created a book to hide it
• Updates to the user profile so that they can see a borrowing history
• Adding details of who borrowed a book
• Adding new categories (fiction and non fiction) to a book
• Fixing the so that the initial invite code expires after the initial use
• Fixing various UX glitches
• Updating the project to run with gunicorn

It sounds like a lot, but with the help of Amazon Q CLI, I was able to get through these in about 20 minutes. The application was now in a pretty solid place, and I didn't think I was going to make any new updates. Now I wanted to do a more thorough review of the code, so I decided to turn to my old friend Amazon Q Developer in the IDE, and specifically /review.

Reviewing the code generated by Amazon Q CLI

I loaded up VSCode in the same directory, created my .gitignore file and then kicked off the initial /review. It found 15 issues - one critical, eight high, six medium, and the rest low and info. It was a useful exercise as it detected a few issues, such as:

• Spotted some gaps where you could access stuff without being logged in (CWE-862)
• Fixed a bunch of cross site scripting issues
• Found a number of Python library package vulnerabilities (gunicorn and Werkzeug)

I was able to address these quickly with minimal impact. It was not all plain sailing though, and I did come across a few paper cuts going through the findings. Here are some things to think about that should save you some headaches:

• Always review the suggested code changes, as they might lead to unintended issues. I found that these occasionally did strange things, for example, disabling the ability to run the application
• Whilst I appreciate the zealous approach to locking down my application, often it failed to understand the broader context (for example, some routes I did not want to lock down by design) and so I had to ignore
• After updates to libraries, I always updated these and then tested the application as I ran into a few issues with the code failing to work due to changes in updates (this tended to be for those that had significant versions changes though, so if there were only minor updates I tended not to worry about them)
• After making my changes, subsequent runs of /review did not "remember" my choices so kept bringing back the same issues.

Despite these, it felt like an essential task going through the /review process, and I was happy that it help identify and then help me fix a number of issues that I just would have missed.

If you have not already done so, I encourage you to check out the /review documentation as it goes into more depth around the different kinds of issues it looks out for.

With the /review done, the project was almost finished.

Updating documentation

During the iterative development phases where I was making changes and adding new features, a lot of changes from the initial code were made. The initial README file was out of date, as well as the initial data model. I still had some time before my journey finished, so I used Amazon Q CLI to update the data model and update the README file. This is the prompt I used:

update the README file to include all the new changes to the application. Can you also add a detailed UML sequence diagram for 1/user registration/login, 2/adding books, and 3/borrowing and returning books

I was happy with the updated README, and the sequence diagrams looked spot on.

The finished application

With my journey nearing its end, I was pretty happy with the end results. Check out the application code in the GitHub repo here, and follow the README on how to get up and running with the application.

Get started with Amazon Q CLI

This was a quick post that showed how I am now incorporating Amazon Q CLI to work with my new favorite editor, Zed, and how I can use it together with Amazon Q Developer as part of development activities.

I hope this blog post has inspired you to want to try Amazon Q CLI for yourself. You can try it for free by signing up for a Builder ID and then downloading the app from here.

Until next time folks!

Made with 🧡 by DevRel!