Skip to main content

AI integration

This template ships configuration that lets AI coding agents work with a generated project out of the box: shared guidance about the project and a pre-approved list of the commands the project uses.

Shipping it is optional: the "Use AI agents" option during initialization (on by default; --ai / --no-ai non-interactively) controls it, and opting out removes CLAUDE.md, AGENTS.md and the whole .claude/ directory from the generated project.

AGENTS.md​

The AGENTS.md file provides agent-agnostic guidance about the project - its architecture, the commands used to lint, test and build it, and the coding conventions to follow. It follows the AGENTS.md convention supported by many AI coding tools.

This template provides an AGENTS.md tailored to the features selected during initialization.

CLAUDE.md​

The CLAUDE.md file is the entry point read by Claude Code. It only includes AGENTS.md, so there is a single source of guidance shared across agents.

.claude/settings.json​

The .claude/settings.json file lists the project commands that Claude Code is allowed to run without asking for confirmation each time - for example linting, testing and building. It is committed to the repository so the whole team shares the same pre-approved list.

The list is derived from the commands documented in AGENTS.md. During initialization, init.sh trims the list to the features you selected, so a project without Docker, for instance, does not pre-approve Docker commands.

.claude/settings.local.json​

The .claude/settings.local.json file holds personal permission overrides. It is git-ignored, so it is never shared with the team or shipped with the project. Use it for machine-specific or experimental permissions.

.artifacts​

The .artifacts directory is a scratch location for temporary AI and developer artifacts - generated plans, notes, reports and other throwaway output. It is git-ignored and never committed, which keeps transient files out of the repository while giving agents and developers a consistent place to write them.

Architecture documentation​

The template can also ship AI-maintained architecture documentation: a narrative walkthrough of how the generated project works, with diagrams, kept in docs/content/architecture/ and derived from the project's actual source code. The directory sits inside the documentation site content tree, so the docs site serves the walkthrough as part of the generated project's documentation.

During initialization, when AI agents are enabled, init.sh asks which diagram format to use: mermaid (the default), plantuml, or none to skip the feature. Non-interactively, pass --ai-arch-docs[=mermaid|plantuml|none] (the bare flag means mermaid) or --no-ai-arch-docs; --no-ai disables AI agents entirely and forces the architecture docs off.

When enabled, the generated project ships:

  • .claude/skills/update-architecture-docs/SKILL.md - a committed Claude Code skill that generates and maintains docs/content/architecture/README.md.
  • docs/content/architecture/README.md - a seed stub that the first skill run replaces with generated content.
  • An "Architecture Documentation" section in AGENTS.md that instructs agents to refresh the documentation after structural changes.

Generation is agent-driven and manual: asking an agent to "update architecture docs" makes it analyze the actual codebase and write docs/content/architecture/README.md as a narrative walkthrough with a component diagram and flow diagrams traced from the real entry points. After any structural change, the standing AGENTS.md instruction tells agents to update the documentation in the same pass. The content derives from the source code: if the documentation and the code disagree, the code wins.

The mermaid format is the default because it needs no toolchain: diagrams are fenced Mermaid blocks inside the markdown, GitHub renders them natively and theme-aware, and the documentation site renders them natively too via its bundled @docusaurus/theme-mermaid theme.

The plantuml format keeps committed .puml sources rendered to committed light .svg files with plantuml -tsvg docs/content/architecture/*.puml. The skill runs plantuml -version before rendering; when PlantUML is not installed, it stops rendering and reports that to the user with install instructions (brew install plantuml on macOS, apt-get install plantuml on Debian/Ubuntu). .claude/settings.json keeps a Bash(plantuml:*) permission only in this variant.

Architecture documentation survives deselecting the documentation site: initializing with --no-docs removes the Docusaurus site, relocates the architecture docs to docs/architecture/, and rewrites every path reference in the generated project to the new location.