Add simple AI Harness

Relates to #1350 and
#1351.

We introduced [thoughtbot agents
rules](thoughtbot/guides#783) to our guides a
few months ago. This commit simply pulls those files into newly
generated Suspenders applications. There's a case to be made that these
should be kept separate, but I like having a single source of truth.

Author: stevepolitodesign

.github/workflows/main.yml

@@ -88,6 +88,13 @@ jobs:
             end
           end
           EOF
+      - name: Verify AI harness files exist
+        working-directory: /tmp/test_app
+        run: |
+          test -f .claude/CLAUDE.md || (echo ".claude/CLAUDE.md not found" && exit 1)
+          test -d .claude/rules || (echo ".claude/rules directory not found" && exit 1)
+          test "$(ls -A .claude/rules)" || (echo ".claude/rules is empty" && exit 1)
+          test ! -f .claude/rules/README.md || (echo ".claude/rules/README.md should not be downloaded" && exit 1)
       - name: Run tests in generated app
         env:
           RAILS_ENV: test

FEATURES.md

@@ -181,3 +181,25 @@ Configuration can be found at `config/initializers/inline_svg.rb`
 [lang]: https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/lang
 [title]: https://github.com/calebhearth/title
 [Prefetch]: https://turbo.hotwired.dev/handbook/drive#prefetching-links-on-hover
+
+## AI Harness
+
+Downloads [AI rules][] from [thoughtbot/guides][] into `.claude/` at app
+generation time:
+
+- `.claude/CLAUDE.md` - a project brief that AI assistants load as context.
+- `.claude/rules/` - coding standards for models, controllers, testing,
+  security, views, and database conventions.
+
+Because the files are fetched from GitHub when the app is generated, they
+always reflect the latest version of the guides at that point in time.
+
+### Customize `CLAUDE.md`
+
+The generated `.claude/CLAUDE.md` is a starting point. Update it with
+project-specific details so AI assistants have accurate context for your
+application — including domain language, architectural decisions, and any
+conventions that diverge from the defaults in `.claude/rules/`.
+
+[AI rules]: https://github.com/thoughtbot/guides/tree/main/rails/ai-rules
+[thoughtbot/guides]: https://github.com/thoughtbot/guides

NEWS.md

@@ -1,5 +1,7 @@
 Unreleased
 
+* Added: AI harness. Downloads `.claude/CLAUDE.md` and `.claude/rules/` from [thoughtbot/guides](https://github.com/thoughtbot/guides/tree/main/rails/ai-rules).
+
 20260325.0 (March 25, 2026)
 
 * Added: Hotwire Spark for live reloading in development.

lib/templates/web.rb

@@ -1,4 +1,6 @@
 require "suspenders/version"
+require "net/http"
+require "json"
 
 # Methods like `copy_file` will accept relative paths to the template's location.
 def source_paths
@@ -69,6 +71,7 @@ def install_gems
   # Finalization
   run_migrations
   update_readme
+  add_ai_harness
   lint_codebase
   commit_final_application_state
 
@@ -516,6 +519,28 @@ def update_readme
       [lang]: https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/lang
       [title]: https://github.com/calebhearth/title
       [Prefetch]: https://turbo.hotwired.dev/handbook/drive#prefetching-links-on-hover
+
+      ## AI Harness
+
+      Downloads [AI rules][] from [thoughtbot/guides][] into `.claude/` at app
+      generation time:
+
+      - `.claude/CLAUDE.md` - a project brief that AI assistants load as context.
+      - `.claude/rules/` - coding standards for models, controllers, testing,
+        security, views, and database conventions.
+
+      Because the files are fetched from GitHub when the app is generated, they
+      always reflect the latest version of the guides at that point in time.
+
+      ### Customize `CLAUDE.md`
+
+      The generated `.claude/CLAUDE.md` is a starting point. Update it with
+      project-specific details so AI assistants have accurate context for your
+      application — including domain language, architectural decisions, and any
+      conventions that diverge from the defaults in `.claude/rules/`.
+
+      [AI rules]: https://github.com/thoughtbot/guides/tree/main/rails/ai-rules
+      [thoughtbot/guides]: https://github.com/thoughtbot/guides
     MARKDOWN
   end
 end
@@ -524,6 +549,25 @@ def lint_codebase
   run "bin/rubocop -a"
 end
 
+def add_ai_harness
+  base_url = "https://raw.githubusercontent.com/thoughtbot/guides/main/rails/ai-rules"
+  api_url = "https://api.github.com/repos/thoughtbot/guides/contents/rails/ai-rules/rules"
+
+  empty_directory ".claude"
+  empty_directory ".claude/rules"
+
+  get "#{base_url}/CLAUDE.md", ".claude/CLAUDE.md"
+
+  response = Net::HTTP.get(URI(api_url))
+  files = JSON.parse(response)
+  files.each do |file|
+    next unless file["type"] == "file"
+    next if file["name"].casecmp?("README.md")
+
+    get "#{base_url}/rules/#{file["name"]}", ".claude/rules/#{file["name"]}"
+  end
+end
+
 def commit_final_application_state
   git add: ".", commit: %(-m 'Changes introduced by Suspenders version #{Suspenders::VERSION}') unless ENV["CI"]
 end