A focused review of the FPGA design
If you're using Claude Code or any other agentic AI tool, you might have tried to run an AI review of your FPGA design. If you weren't happy with the result, this is a suggestion on how to improve it.
Namely, it's possible to focus the AI agent's review on certain topics, and in various ways tell it how to perform the review. A skill set does exactly that: It shapes the agent's behavior in order to run the review based upon correct information, and not just anything the neural network was trained on. What is "correct information"? It's the facts written in the skill set.
A skill set based upon this website's content is available for use. If you want to give this a try, put your FPGA design's files where the AI agent can reach them, and write a prompt like this:
> Using the skill set from https://github.com/billauer/01signal-review, perform a review of the FPGA project. Write out the HTML files.
The AI agent (Claude Code or whatever you have) will run a review primarily based upon the skill set in that GitHub repository, which in turn reflects the content on this website. Accordingly, the review report will be focused on topics mentioned here. For example, there’s a series of pages discussing resets on this website. Is your design on par with those? Maybe you forgot to reset one little register, and maybe there’s a more fundamental mistake? The review report will tell you. Hopefully. An AI review isn't deterministic.
Using AI to check your design: The good and the bad
As it turns out, AI agents are pretty good at reading code and finding mistakes. But the problem with them is that they often make up mistakes that don’t exist. And when they do, they usually come up with a very convincing explanation, which tends to be based upon one or more incorrect factual claims. Maybe the neural network was trained on incorrect information, maybe it draws an incorrect conclusion from correct information, and maybe something else. Some people call this hallucinations, I call it rubbish.
Another annoying issue is prioritizing: For example, an AI agent is likely to put syntax errors and other "build-breakers" at high priority in the review. There's a point in doing so, as the design won't compile until these errors are fixed. But there's rarely a benefit in mentioning such errors in a review report: The tools usually point at the problem when they refuse to compile. It's only when the issue is non-obvious that it's worth mentioning in the review.
And all too often, AI tools get hung up on a minor issue and make a chicken out of a feather. It's easy to dismiss the entire review when the first topics sound like nonsense.
These issues are solved to a great extent with a skill set.
How a skill set helps
A skill set consists of several files, mostly containing plain human-readable text. It’s a bit like an instruction book for the AI agent on how to perform the design review (or any other task, for that matter). This text does mainly three things:
-
Define what is true: What is correct and what is incorrect, in terms of facts and design practices.
-
Define priority: Outline what is important and what is relatively forgivable.
-
Define how to carry out the review. This is where systematic instructions are given to the agent, dividing the review assignment into separate tasks, so that the review is carried out in a methodical way. This is usually done in the main skill file (typically named SKILL.md).
The first and second parts help reduce nonsense in the review report. These are like a condensed tutorial on the topics to examine during the design review, setting both facts and priorities. By explicitly mentioning a list of things to check, the AI agent relies more on facts that are correct and solid, and less on its own built-in knowledge.
The third part organizes the review process, but has a more important role in 01signal’s skill set: It includes two final steps where the AI agent verifies its own report.
In the last step, a separate AI agent starts from fresh and acts as an inspector. It goes through the entire report, and verifies that all factual claims are taken directly from the skill set. Factual claims not supported this way are reworded in the report so that they use doubtful language (for example, a rhetorical question), as opposed to the well-known confident tone AI tools usually have. However, the AI tool can't reach any conclusion without using its own baked-in knowledge. And yet, it should be clear in the report which part is substantiated (from the skill set, using confident language) and which isn't (the opposite).
And the content in the skill set isn't carved in stone either, of course. It can be incorrect and lacking. It's no coincidence that it's published on GitHub.
This is not a substitute for knowledge
I've said it elsewhere on this site, and I'll say it again: There is no substitute for our brains, and there's no substitute for acquiring knowledge. Debugging tools and AI tools are helpful, but in the end, it's up to us humans to make the decisions.
An AI review won't make your FPGA design work. But it can point you in the right direction. And because the skill set is based upon the pages on this website, the review tells you not only what may be wrong, but also where to read more about it.
So if you made a mistake because of a plain human error, fix it and call it a day. But if it was because you didn't know something, stop and take the time to fill the gap. This is, after all, the advantage of a skill set derived from a website.