# Hedge-Ops Software URL: https://hedge-ops.com/ Software & Solutions. A data-driven approach to career management. --- # InSpec Tutorials URL: https://hedge-ops.com/inspec/ Learn InSpec compliance as code with this step-by-step tutorial series. From Hello World to Azure resource validation.
InSpec Tutorial Series

Learning InSpec is completely approachable, and if you follow these tutorials, you'll be writing compliance as code in no time!

## Tutorial Series - [Day 1: Hello World](/posts/inspec-basics-1) - [Day 2: Command Resource](/posts/inspec-basics-2) - [Day 3: File Resource](/posts/inspec-basics-3) - [Day 4: Custom Matchers](/posts/inspec-basics-4) - [Day 5: Creating a Profile](/posts/inspec-basics-5) - [Day 6: Ways to Run It and Places to Store It](/posts/inspec-basics-6) - [Day 7: How to Inherit a Profile from Chef Compliance Server](/posts/inspec-basics-7) - [Day 8: Regular Expressions](/posts/inspec-basics-8) - [Day 9: Attributes](/posts/inspec-basics-9) - [Day 10: Attributes with Environment Variables](/posts/inspec-basics-10) - [Day 11: Validating Azure Resources with InSpec Azure](/posts/inspec-basics-11) ## Additional Resources - [Setting Up Compliance](/posts/setting-up-compliance) - [Tour of Chef Compliance](/posts/tour-of-chef-compliance) --- # Blog Posts URL: https://hedge-ops.com/posts/ --- # How We Work URL: https://hedge-ops.com/services/ Three engagement types — Audit, Sprints, Retainer — designed to align delivery, organization, and relationships. --- # Impeccable Design URL: https://hedge-ops.com/posts/impeccable-design/ Learn how to deslop your website with Impeccable. Don't worry, you're not the only one who is using AI to create your website. If you're a solopreneur or someone just getting started trying to validate your idea, you probably can't afford a great marketing team to create your website. So the first iteration is likely going to be an AI-generated affair. The very first website design that I created was total AI slop. No shame in admitting that. That was back when everyone was super excited about creating things _quickly_ with AI that would otherwise take weeks. The term "AI slop" hadn't been coined yet, but it was surely on the horizon. As time went on, I started to realize how crappy my website design was, and people were telling me that it confused them. So I began iterating on it, and honestly, I am still iterating based on data. My style, taste, messaging, and branding cannot be replaced with AI if I am to expect positive results. I need to stand confident in those choices, and that means that I can't let AI hijack those choices. But what if I don't know if I'm deluded? Well, that's where [Impeccable](https://impeccable.style/) comes in. > The missing design vocabulary for agents. Impeccable strips the AI slop tells and bad defaults out of every design discipline, from type to motion to copy. -- impeccable.style So basically, it trains your AI agent on all the good skills that real designers use so that it can evaluate your site and tell you how to make it better. Truth be told, if you have the budget, then I still recommend that you pay a human designer, but if you don't, this is the next best thing. Here's a preview: - [The Setup](#step-1-the-setup): Install Impeccable and teach it who you are and what you're building. - [Documenting what's there](#step-2-documenting-what-s-there): Capture your current design as a baseline. - [Diagnose](#step-3-diagnose): Let it grade your site and find the slop. - [Fix](#step-4-fix): Work through the problems, one command at a time. - [Iterate live (optional)](#step-5-iterate-live): Fine-tune elements right in the browser. - [Polish & re-score](#step-6-polish-re-score): Smooth the rough edges and reassess your grade after changes. Let's get started! ## Step 1 - The Setup ### Prerequisites - Node.js is installed and `npx` is on your path. - Your site exists in code. - An AI agent harness is installed (Claude Code, Codex CLI, Cursor CLI, etc). Impeccable does allow you to start from scratch, but for this tutorial, I will assume that you're starting from an existing site that you're managing with git. I created a simple, single-page, static website called "Aspen" for this exercise. You're welcome to clone it from [here](https://github.com/hedge-ops/aspen) if you'd like. ### Installation The first thing you're going to want to do is install [Impeccable](https://impeccable.style/). If you install it globally (`~`), then all of your projects will have access to it. Otherwise, you may install it at the root of the repository that houses your website. Run this to install: ```bash npx impeccable install ``` When you run this, it will detect which agent you will use and install for all detected harnesses. Then it will ask if you want to use the tool just for this project locally or all projects globally. Choose which you prefer. ![Impeccable installation in agent harness](/assets/blog/impeccable-installation.webp) ### Initialization #### [`/impeccable init`](https://impeccable.style/docs/init/) In your agent session, run [`/impeccable init`](https://impeccable.style/docs/init/), and stop! This is the most important step. Don't click your way through this. I know you want to get to the fun, design stuff, but this is where the foundation is laid. Don't let your agent lay the foundation or you're going to be back in the slop-camp that you started in. There is a risk that your agent will give you multiple choice questions, but resist the urge to use its choices. Instead, force yourself to write your own answer to every question. Hopefully, you've done some marketing exercises answering some of these questions already, in which case you can draw from your resources, but if you have not, then take as much time as you need to get these answers crystal clear. For my tutorial, I asked it to not provide multiple choice answers, and this is what it asked in return: ```txt 1. Who is this for? Picture the specific person who lands on this page - what's going on in their world, and what made them come looking? 2. What is the thing, and what job does it do for them? In your own words, what does it actually help them accomplish? 3. When they leave the page, what's the one thing you most want to have happened - a concrete action, a clear understanding, or a particular feeling? ``` A common rookie mistake of software companies, one that I have made myself, is to cast too wide of a net. We see all the possibilities for anyone in the world to use our software so we keep the messaging vague to not push anyone away. While it's true that our total addressable market (TAM) is ginormous and that there are so many use cases for our software, the messaging ends up super vague, not speaking to anyone. Right now, you need one beachhead, the ideal customer that you want to speak to today, the one you have in mind when you're building. Before you answer any of your agent's questions, do this fill-in-the-blank exercise as thoroughly and specifically as you can: > Our `[product/service]` helps `[customer segment]` who want to `[jobs to be done]` by `[verb]` `[customer pain]` and `[verb]` `[customer pain]`, unlike `[competitor's solution]`. And if you haven't validated this statement with real customer feedback, then that's your homework. Talking to as many people as possible will make this exercise much easier, so if it's very difficult, that's your signal to put the design on hold while you go set up some conversations. (Stay tuned, as this is an upcoming topic I plan to cover.) The next round of questions my agent asked me was more tailored to my previous answers, so yours will likely be different: ```txt Round 2 - personality and guardrails. Three questions: 1. Voice in three words. If this brand were a person talking to that stretched-thin solopreneur, how would you describe its personality? Reach for concrete, physical words ("warm and direct and unhurried") over "modern/clean." 2. References - and the specific thing about each. Name 1–3 actual sites, apps, or brands whose feel is right, and the one concrete thing each nails for you. (Equally useful: anything you've seen in this space that feels wrong - an anti-reference - and why.) 3. Accessibility bar. Any requirement to lock in (e.g. WCAG 2.1 AA contrast, keyboard nav, reduced-motion), or known user needs I should design around? ``` This is where your taste comes into play. Think of the adjectives that describe the vibe you want to portray. My answers to this for my fake website, Aspen, were: ```txt 1. warm, confident, encouraging, honest 2. impeccable.style, elegant ski lodge chic, minimalist, luxury; anti-references include: loud, flashy, crowded, like salesforce.com, lattice.com 3. your recommendation ``` After you answer these questions, your agent is going to create a first pass at a `PRODUCT.md` file. This will contain information about your: - Users - Product purpose - Brand personality - Anti-references - Design principles Go ahead and click `Yes` that you want it to create that, but you better believe we're going to come back and edit that. When you click `Yes`, it will create another file called `.impeccable/live/config.json` and may update your `CLAUDE.md`. When that is complete, open up your newly created `PRODUCT.md` file, and camp out there for a while. Go over it with a fine-tooth comb. I know, I know, you want to move on, but _this is the work_, y'all. Read through every line. If you start to gloss over what you're reading, take that as a sign that it's not clear enough. Delete the line and write it in your own words. Likewise, if there's just too much information in there, delete anything that's not adding clarity, anything that's not a sharp, concise thought. ## Step 2 - Documenting what's there ### [`/impeccable document`](https://impeccable.style/docs/context/) After you complete your initialization, your agent will likely tell you that it's time to run [`/impeccable document`](https://impeccable.style/docs/context/). If you were starting a new project, then you would choose which direction to take your colors and styles at this point using the `--seed` flag. But since we're editing an existing project, your agent will read from your existing CSS and templates, and just document what's already there. Don't worry, you aren't stuck with that design! You can say yes to it creating your `DESIGN.md` because it's just documenting it so that you have a starting point. It will edit this file as you go through the other steps later. Before you move onto the next step, though, get an idea for what kind of style you want to migrate to. If you don't know what your style is, then go dig around. Find 2-3 real sites or brands that you really love and want to emulate, and find a couple more that you hate and want to avoid. You started this exercise of determining what you like and dislike when you were doing your `init`, so you're just refining it here. When your agent is finished with this step, it will have written `DESIGN.md` and `.impeccable/design.json`. Then it will probably tell you to run [`/impeccable critique`](https://impeccable.style/docs/critique/). ## Step 3 - Diagnose ### [`/impeccable critique`](https://impeccable.style/docs/critique/) Moment of truth! AI is going to tell you where the AI slop is based on the documents you've created thus far. Does your site look like it should according to the documents? Run [`/impeccable critique`](https://impeccable.style/docs/critique/), and wait for the painful truth. It will grade you on the [10 industry standard heuristics](https://www.nngroup.com/articles/ten-usability-heuristics/). Here is the verdict on my fake "Aspen" website: ```txt Design Health Score #: 1 Heuristic: Visibility of System Status Score: 2 Key Issue: Every CTA (Download, Get Started) points to # - no destination, no feedback ──────────────────────────────────────── #: 2 Heuristic: Match System / Real World Score: 3 Key Issue: Plain, human copy; the grove metaphor is consistent and clear ──────────────────────────────────────── #: 3 Heuristic: User Control and Freedom Score: 2 Key Issue: Anchor nav works, but the primary action leads nowhere ──────────────────────────────────────── #: 4 Heuristic: Consistency and Standards Score: 3 Key Issue: Internally consistent (emerald/amber, pill buttons, card rhythm) ──────────────────────────────────────── #: 5 Heuristic: Error Prevention Score: 3 Key Issue: n/a - no forms to get wrong ──────────────────────────────────────── #: 6 Heuristic: Recognition Rather Than Recall Score: 3 Key Issue: Clear nav labels; "Align/Guide/Partner/Network" introduced without definition ──────────────────────────────────────── #: 7 Heuristic: Flexibility and Efficiency Score: 2 Key Issue: No skip-link; mobile nav disappears with no replacement ──────────────────────────────────────── #: 8 Heuristic: Aesthetic and Minimalist Design Score: 2 Key Issue: Reads generic-AI; visual treatment fights the brand you defined ──────────────────────────────────────── #: 9 Heuristic: Error Recovery Score: 2 Key Issue: n/a - no states, but also no 404/empty handling anywhere ──────────────────────────────────────── #: 10 Heuristic: Help and Documentation Score: 2 Key Issue: No FAQ, pricing, or support; "Free to try" unexplained ──────────────────────────────────────── #: Total Heuristic: Score: 24/40 Key Issue: Acceptable - works, but generic and off-brand Anti-Patterns Verdict Does this look AI-generated? Yes - unmistakably. ``` AI clearly assessed that this is unmistakably an AI-generated website. Most sites land between 20-32, so 24 isn't an absolute failure, but the verdict is that it's _generic_ and _uninspired_. It goes on to say what's working, what's not working, and what the priority issues are. My agent showed me the `Priority Issues`, for example, here's just one of them: ```txt - [P1] Visual identity is generic and off-brand. The emerald/amber emoji-grove reads as friendly-SaaS, the exact register PRODUCT.md rejects. Why it matters: a quiet-luxury audience judges credibility on craft; this looks templated. Fix: re-skin to the ski-lodge palette (evergreen + ember on snow/wool) with the Spectral/Hanken type pairing. Command: /impeccable typeset then /impeccable colorize (or /impeccable shape for a fuller rework). ``` Having the exact commands to run for each problem is really useful. I like that it also tells you what's working so that you don't try to "fix" that. It will then ask you if it can create a file called `.impeccable/critique/_tmp_body.md`, where it's going to track the critiques. Once it does that, it's ready to get to work, and it asks you where you want to start: ```txt Now, to shape the action plan: ──────────────────────────────────────────────────── ← ☐ Priority ☐ Scope ☐ Copy ✔ Submit → The biggest finding is that the visuals (emerald/amber emoji-grove) contradict the quiet-luxury brand, while the copy is already on-voice. Where do you want to start? 1. Re-skin to the brand Tackle the P1 visual-identity gap first: palette + type toward ski-lodge chic (evergreen/ember/snow, Spectral + Hanken). Highest-impact, biggest scope. 2. Kill the loudest tells Quick wins first: remove the gradient headline and the emoji-card grid pattern. Smaller, fast, lowers the 'AI made this' read immediately. 3. Fix the functional gaps Mobile nav disappearing + dead CTAs first - the P2 usability issues - before touching aesthetics. 4. Type something. ─────────────────────────────────────────────────── 5. Chat about this ``` And hey, if you're like me, you're overwhelmed at this point, and that's okay! However you answer, you've got two ways to actually proceed: 1. Jump in and start tackling it. If you say that you want to work on it, it will tell you which commands to start running. 2. Tell it to create a ticket for each area of work, with enough detail and context for another agent to work on it. (This assumes that your agent has permission to create tickets in your system.) Note that you can run `critique` whenever you want. It will always give you a current assessment. ## Step 4 - Fix ### `/impeccable ` So let's say that we're ready to jump in and start fixing things. For this tutorial, I'll select `1. Re-skin to the brand` from Step 3's last prompt. The next thing it asks me is: ```txt How much do you want to take on in this pass? 1. Top 3 (the P1s) Visual identity, gradient headline, and the card grid - the three brand-defining problems. 2. Everything found All P1s and P2s: re-skin, headline, card grid, mobile nav, dead CTAs, plus the minor a11y/contrast notes. 3. One thing at a time Start with a single command and decide the next step after you see the result. 4. Type something. ─────────────────────────────────────────────────── 5. Chat about this ``` I'll select `1. Top 3 (the P1s)`. When I selected that, it's now asking me if I want to keep the copywriting that I have in there already or change it. It's warning me, however, that the copy is the strongest part of the assessment, so it recommends that I leave it. I will agree with it and move on. Now it's telling me what the plan is and which commands will get us there. (Get familiar with the commands available by taking a look at the [docs](https://impeccable.style/docs/).) ```txt ⏺ Locked in: re-skin to the brand, top-3 P1s only, keep the copy verbatim. Here's the plan, ordered so the new identity is established before the layout work builds on it. Action Summary 1. /impeccable typeset - Establish the type system: Spectral (light weights) for display/headings + Hanken Grotesk for body, replacing the system-UI font. This pass also kills the gradient-clipped headline (P1 #2) - solid Charcoal Ink with emphasis via weight/size, no bg-clip-text. Copy stays word-for-word. 2. /impeccable colorize - Apply the ski-lodge palette (Aspen Evergreen + Hearth Ember on First-Light Snow / Warm Wool), retiring the emerald/amber emoji-grove and the gradient hero wash. Resolves the core P1 visual-identity gap. 3. /impeccable layout - Rework the identical six-up emoji-card grid (P1 #3): introduce asymmetry / a featured item and drop the emoji icons, so the Features section stops reading as a template. Structure and copy preserved; only arrangement and emphasis change. 4. /impeccable polish - Final pass once the three above land: tighten rhythm, focus states, hairlines, and the reduced-motion guard, and confirm the gradient/emoji/pill tells are fully gone. (Out of scope this pass, per your call: the P2 mobile-nav and dead-CTA fixes, and any copy rewrites. They're captured in the saved snapshot for later.) ▎ You can ask me to run these one at a time, all ▎ at once, or in any order you prefer. ▎ ▎ Re-run /impeccable critique after the fixes to ▎ see the score move off 24. Want me to kick off /impeccable typeset now? ``` So I said `yes` and am allowing all edits. When it completes, it rebuilds the website locally, I look at the localhost preview, and it urges me to run the next command upon approval. I like the typeset changes, so I forge ahead. This is the point at which I can request a change of direction. The typeset was good, but I already know that I'm unhappy with the colors. When it runs [`/impeccable colorize`](https://impeccable.style/docs/colorize/) I will need to inspect carefully. After the [typeset](https://impeccable.style/docs/typeset/) and coloring changes, we ended up going from this to this for the bottom half of the page: ![Before and after typeset and color Impeccable changes](/assets/blog/aspen-typeset-and-color.webp) I don't hate it. We're making progress toward the chic, ski lodge vibe, so I'm going to move on and see how it plays out, saying `yes` when it asks `Want me to run` [/impeccable layout](https://impeccable.style/docs/layout/)`?` I said `yes` again, and mind you, it's only fixing the top priority items, so we can see it improving little by little with each command. Next, it wants to run [`/impeccable polish`](https://impeccable.style/docs/polish/), and then it will be complete for this pass of things. If this were not a tutorial, then I'd keep going until the heuristics score was as high as I could get it and until I really _loved_ it. And honestly, if we decide to change our name to `Aspen`, then who knows, maybe this will become a real project (if you read this far, tell me if you like the name). The `polish` command leaves me with a wall of text, but it's a good statement of where we currently stand and what else is left to do: ```txt What the polish pass added Accessibility - Skip-to-content link - sr-only until focused, lands on the new
landmark. - Visible keyboard focus on every link/button (evergreen ring + offset), with a snow ring override on the ember CTA so it doesn't vanish against the dark drench. - Decorative logos marked aria-hidden (the adjacent "Aspen" wordmark names the link). - Anchor targets get scroll-margin-top: 5rem so the sticky header stops covering section tops on jump-nav. Motion - prefers-reduced-motion: reduce guard - disables smooth scroll and collapses transitions to near-instant. The last emoji, replaced with on-brand marks - Hero badge 🌿 → a small evergreen dot. - Testimonial 🌳 → a centered evergreen hairline rule (echoes the feature-panel accent). - Footer 💚 → an inline evergreen heart SVG (aria-label="love"), keeping the sentiment without an emoji. Contrast was already verified during colorize (AA throughout); these changes don't touch text colors. Where things stand All three critique P1s are resolved (visual identity, gradient headline, card grid) and the polish items are closed. The page now reads as the Quiet Lodge: Spectral + Hanken type, evergreen/ember on snow/wool, an editorial Features section, and a clean a11y baseline. Two things I want to flag honestly: 1. DESIGN.md is now stale - you had me document the old emerald/amber state as a baseline. The implementation has moved to the ski-lodge tokens in src/input.css. Worth re-running /impeccable document to capture the real, current system. 2. static/favicon.svg is likely still the old-palette mark - I didn't touch it; it'll want re-toning to match. Still parked from the critique (out of the P1 scope you chose): the P2 mobile-nav disappearing and dead href="#" CTAs. Suggested next - /impeccable critique templates/index.html - re-run to see the score move off 24 now that the P1s are fixed. - /impeccable document - refresh DESIGN.md to the ski-lodge system. - /impeccable adapt - pick up the P2 mobile nav when ready. Want me to re-run the critique to measure the improvement, or refresh DESIGN.md? ``` This is a good stopping point for the command section of the tutorial, as your agent can surely guide you from here. ## Step 5 - Iterate live ### [`/impeccable live`](https://impeccable.style/docs/live/) Okay, let's say you need to do some fine tuning but you need to see the changes live in order to do that. Well, that's where [`/impeccable live`](https://impeccable.style/docs/live/) comes in. Live mode injects a helper into the page that your browser loads. It allows you to click something (an element), choose an action to take (`pick`, `insert`, `detect`). If you selected `pick` or `insert`, your agent will generate three different variants that you can switch through right there so you can decide what you like best. Selecting `detect` will find anti-patterns. ![Impeccable live helper](/assets/blog/impeccable-live-helper.webp) **Hot Module Replacement (HMR):** If you're using a hot-reload dev server like Vite, Next, Nuxt, SvelteKit, etc, then you're golden. You just start your dev server as you normally would, then run [`/impeccable live`](https://impeccable.style/docs/live/). You'll open your local dev URL, and the helper will be there ready for you. **Static Site Generators (SSG):** If you're like me and are on Zola, Hugo, Jekyll, Eleventy, Astro-static, or any other static-site generator, then your agent will need to do an extra step that will make it function slightly differently. This is because these dev servers serve your site _from memory_, not from the built files on disk where the helper gets injected. So the helper never actually reaches your browser. No big, though, just tell your agent to: 1. Build the site. 2. Inject the helper into the built output. 3. Serve that with a plain static server. 4. Run the poll loop in the background. Then you'll just open the URL it hands you and start clicking. If you accept a change, it triggers a quick rebuild so that you can see the change. ### Picking & inserting elements (HMR & SSG) Now, you'll click the `Pick` or `Insert` button, then select the element that you want to change. Once it's selected, you type into the comment field what you want to change or what types of options you want your agent to give you. ![Impeccable live element picker](/assets/blog/impeccable-helper-picker.webp) And heads up, you may want to have your browser and your agent session side by side so you can tell when it's asking you for things. I sat on this screen on the left for longer than I care to admit before I realized that the agent was asking me to proceed. ![Impeccable live with VSCode side by side](/assets/blog/impeccable-live-vscode.webp) Once I told it `Yes`, it showed me these three options, I told the agent that I liked Option 3 the best, and it changed it for me. ![Impeccable live options](/assets/blog/impeccable-live-options.webp) I'm honestly not sure here if selecting your choice is different in an HMR environment than it is with an SSG environment, but for me, I had to tell my agent directly in the agent conversation (not the helper in the browser) which option I wanted to go with. Honestly, I don't really like `live`, especially with my SSG. It's a bit kludgy, and from time to time, the helper bar just disappears. I find the `picker` and `insert` functions work sometimes and not others. I'm sure that those with HMR sites have a better time with it, but for me, I just stick to the conversational nature of working with my agent on it. And if I want to change something manually, then I update the code, look at it, and ask my agent to run another critique to make sure I didn't do something dumb. ## Step 6 - Polish & re-score ### [`/impeccable `](https://impeccable.style/docs/harden/) The important thing to know with Impeccable commands is that they're meant to be executed in order. When you look at the [docs](https://impeccable.style/docs/), there are several sections of commands: - Create (if you're starting from scratch) - Evaluate - Refine - Simplify - Harden And note that they do have System commands listed at the bottom, which include `document` and `init`. But of course, those do get run in the beginning. Everything else, however, should be run in order. You don't want to _harden_ your site if you haven't even _evaluated_ it yet. And theoretically your agent should be taking you through this order as well. If they're not, then familiarize yourself with it so that you can know if your agent is going rogue. You will get to a point where you're pretty happy with all of the changes that came from your critique and you will begin polishing your site. This is the fun part where you are able to smooth off any rough edges and optimize. Once you finish with your [`/impeccable polish`](https://impeccable.style/docs/polish/), then you can go back to the top of the command list again, and re-run [`/impeccable critique`](https://impeccable.style/docs/critique/) to see what else surfaces and what score you have now. My guess is that it will have drastically improved and that you'll be much happier with your results. I never actually finished the impeccable design for Aspen. However, even after just the few commands that I ran for this blog post, I was able to make marked improvements. I'd love to see your before and afters! Share them with me on socials. ![Before and after using Impeccable on Aspen site](/assets/blog/aspen-before-and-after.webp) Regardless of which you _like_ better, you can see that the one on the right has the intention of conveying the vibe of a chic ski lodge. Not so much on the left, which rather conveys, "Let's throw something up there on the internet real quick." --- If you'd rather not navigate all of this on your own, [get in touch](mailto:support@hedge-ops.com?subject=Request%20for%20Info%20on%20Services&body=Hi%20Annie%20and%20Michael%2C%0A%0AI%20found%20you%20through%20%5Bhow%5D%20and%20I%27m%20interested%20in%20learning%20more%20about%20your%20consulting%20services.%0A%0AWhat%20we%27re%20dealing%20with%3A%0A%0A%0AWhat%20I%27m%20hoping%20to%20get%20out%20of%20a%20conversation%3A%0A%0A%0AName%3A%0ACompany%3A%0ABest%20way%20to%20reach%20me%3A). I'm happy to set up a call to see how I can help. (You can also use that link to simply ask clarifying questions about this post.) I sincerely hope this was helpful for you. Good luck on your design journey. You got this! --- # AEO: Getting Started URL: https://hedge-ops.com/posts/answer-engine-optimization-playbook/ Everything we changed on hedge-ops.com and people-work.io to be cite-worthy to ChatGPT, Perplexity, and Claude. Check out the AI prompts we used to do it. Last year I began hearing people talk about AEO, Answer Engine Optimization, and how important it is to get AI to recommend your product or services as people are going to AI for answers for more of the questions they used to type into Google Search. I went to AI anonymously and tried to get it to recommend my product to me when I asked it specific questions that my product provides answers for. I wasn't too surprised when it didn't know anything about my product or what it did or what problems it solved, but I was honestly pretty discouraged. > I felt like it was impossible for a small business to ever get recommended on AI platforms when the behemoth companies already own SEO success and have full-time, dedicated staff working on AEO solutions. I felt overwhelmed. -me Then I listened to [Ethan Smith's AEO playbook on Lenny's Podcast](https://www.lennysnewsletter.com/p/the-ultimate-guide-to-aeo-ethan-smith), and hope was sparked. I took what I learned and built a game plan from there, one that even exceeded his playbook. I'm going to walk you through my ongoing practice of AEO and what changes I've seen over the last six months. I'll show you what we changed on [hedge-ops.com](https://hedge-ops.com) and [people-work.io](https://people-work.io), the types of prompts I used to make the changes, and where AEO continues to show me where I have a lack of clarity in my business messaging, giving me opportunities for improvement. ## Intro to AEO - What is AEO and why does it matter? ```md AEO = SEO + citation optimization ``` You can think of AEO as SEO for AI, but, more specifically, it's SEO plus citation optimization. SEO will rank your relevance, but AEO will determine whether or not AI should cite you as a resource for a particular topic. AEO is not a one and done exercise but an ongoing practice. I will show you certain things that you can put in place and forget about it, but at the heart of AEO is building trust and credibility, which takes time and consistency. --- ## The four levers small businesses can pull for good AEO 1. [**Structured data**](#lever-1-structured-data-the-hidden-labels-ai-reads) - the hidden labels AI reads 2. [**Semantic HTML**](#lever-2-semantic-html-writing-pages-ai-can-quote) - making pages that AI can extract and quote 3. [**llms.txt**](#lever-3-llms-files-publishing-for-ai-directly) - publishing for AI directly 4. [**Off-site presence**](#lever-4-off-site-presence-building-credibility-out-in-the-wild) - building credibility out in the wild --- ## Lever 1: Structured data (the hidden labels AI reads) If you're not technical and don't know what this is, fear not. It's not as complicated as it sounds. Let me show you. ### What structured data is, in plain English Our websites have two different views. There's one that we can see and one that the machines can see. What we can see is a very decorated and lovely view designed for human eyes. ![Screenshot of People Work website](/assets/blog/website-screenshot.webp) What the machines can see is basically all of the metadata that a machine needs to make a determination on your website. ![Screenshot of structured data for People Work website](/assets/blog/structured-data-screenshot.webp) There is JSON code embedded in every page that gives AI the stripped down version of what it needs to know. On the left you can see the JSON code, and on the right you can see a more human-readable version of the same thing. To see this for your own website, go to https://validator.schema.org/ and enter in your URL. Before I worked on my AEO, this view was abysmal. It was missing data, had outdated descriptions, and overall lacking. ### The `@graph` pattern (and why a single block beats multiple) There are two ways you can hand over this data from above to an AI: as separate index cards or one connected map. Most sites do it the first way: ```html ``` ```html ``` ```html ``` These blocks don't reference each other, so AI has to guess if and how they're related. On the other hand, if an AI lands on this very blog post that you're reading, it will know that: - It was written by Annie Hedgpeth. - She is the co-founder of Hedge-Ops Software. - They created [People Work](https://people-work.io). - There's more on LinkedIn and all of these other references on the connected map. It's able to verify my credibility this way because it "asked around", just like you would if you were verifying a person's credibility. We collapse everything into one block with one `@graph` array simply so that it's easier to reason about the site. Every page on my sites emits exactly one ` ``` Notice where it says `sameAs` above? It's exactly what it looks like. You're telling AI, "Hey, these sites vouch for me." In technical terms, these profiles help to disambiguate the entity. #### Structured Data Prompt Here's the prompt you'll use, but before you do that, you'll need to edit it. So read through it and replace all text in brackets `[ ]` with your unique data (and remove the brackets): ```txt I want to add JSON-LD structured data to every page of my website for Answer Engine Optimization. About my business: - [Company name, one-sentence description, website URL] - [Founder names and roles] - [Social URLs you want AI to verify you against (LinkedIn, X, YouTube, etc.)] - [The page types your site has (home, services, blog, etc.)] Page types on my site: [examples: home, services, blog posts, etc.] Generate a single JSON-LD @graph block I can put in the of every page. Requirements: - Exactly one