agentic-coding-ig-development

features	FHIR IG AI assisted Claude Code Implementation guide Markdown
languages	Markdown

Agentic FHIR Implementation Guide Development

Traditional FHIR Implementation Guide development is complex and time-consuming. Creating and validating FHIR StructureDefinition resources and terminology resources requires deep technical expertise, which led to the development of additional tooling like the FSH (FHIR Shorthand) language.

With the advent of Large Language Models, we can now explore a different approach: describing all profiles, code systems, and value sets in natural language and having an LLM generate the complete Implementation Guide from those descriptions.

This project demonstrates how the Aidbox FHIR Server enables LLMs to immediately test and validate each generated resource, creating a seamless AI-assisted development workflow for FHIR Implementation Guides.

Key Features

• Documentation-Driven Development: Natural language markdown specifications automatically converted to FHIR resources
• AI-Assisted Resource Generation: Claude Code generates compliant FHIR resources from requirements
• Integrated Testing Environment: Local Aidbox FHIR server for real-time validation and testing
• Comprehensive Test Suite: HTTP-based automated testing for all resource types
• Publication Ready: Direct integration with HL7 FHIR IG Publisher

Prerequisites

• Docker and Docker Compose - Container orchestration
• Claude Code - Primary tool for AI-assisted IG development
• httpyac - HTTP client for testing FHIR resources
• HL7 FHIR IG Publisher - Official FHIR IG publishing tool (publisher.jar) - Download and put the publisher.jar in the ig-publisher directory
• Aidbox - Local FHIR server for testing and validation

Quick Start

1. Clone the repository:

   git clone git@github.com:Aidbox/examples.git 
   cd examples/agentic-coding-ig-development

2. Start the FHIR server:

   docker compose up -d

3. Initialize Aidbox:

   • Open http://localhost:8080 in your browser
   • Log in and initialize the instance with your Aidbox account
   • The init bundle automatically configures:
     • Client with Basic authentication (basic:secret)
     • Access policies for the client

Project Structure

agentic-coding-ig-development/
├── .claude/                     # Claude Code configuration
│   ├── commands/                # Custom development commands
│   │   ├── publish-ig.md        # Publish IG using publisher.jar
│   │   ├── test-cs.md           # Test and validate CodeSystems
│   │   ├── test-profile.md      # Test and validate Profiles
│   │   ├── test-vs.md           # Test and validate ValueSets
│   │   └── view-ig.md           # View published IG in browser
│   └── settings.local.json      # Local Claude Code settings
├── CLAUDE.md                    # Claude Code main configuration file
├── README.md                    # Project documentation  
├── docker-compose.yaml          # FHIR server orchestration
├── ig-publisher/                # IG publisher configuration
│   ├── ig.ini
│   ├── ig.json
│   └── input/ 
├── src/                         # FHIR resource definitions
│   ├── CS/                     # CodeSystem resources
│   ├── VS/                     # ValueSet resources
│   └── Profiles/Extensions/    # Profile and Extension definitions
├── target/                     # Generated canonical resources (empty)
└── test/                       # HTTP-based test suite
    ├── CS/                     # CodeSystem tests
    ├── VS/                     # ValueSet tests
    └── *.http                  # Individual test files

Development Workflow

1. Generation of the FHIR Resources from the MD definitions.

Write requirements in natural language markdown files in the src directory.

Couple of examples:

• CodeSystem definition CSIdentidadGenero
• ValueSet definition VSIdentidadGenero
• Profile definition PacienteCl

Ask Claude to generate the FHIR resource for the definition in the markdown file.

claude  
> Generate FHIR resource for CSIdentidadGenero codesystem

Check the generated resources in the target directory. Couple of examples:

• CodeSystem definition CSIdentidadGenero
• ValueSet definition VSIdentidadGenero
• Profile definition PacienteCl

2. Resource Testing

We need to test the generated resources and it's very easy to do that with Aidbox FHIR Server.

The testing methodology is described in the following commands:

• test-cs.md - test CodeSystem resources against FHIR server
• test-vs.md - test ValueSet resources and expansion
• test-profile.md - test StructureDefinition profiles with sample data

Ask Claude to test the resources:

Test CodeSystems:

claude
> /test-cs CSIdentidadGenero

Test ValueSets:

claude  
> /test-vs VSIdentidadGenero

Test Profiles:

claude
> /test-profile PacienteCl

Take a look at the test cases that were generated in the test directory:

• test-cs.http
• test-vs.http
• test-profile.http

Each test run provides a detailed log of executing the test cases - you should be able to see the log files next to the .http file.

The stable .http file with all the test cases gives you the ability to rerun all the test cases manually when needed and enables the LLM to iterate on fixing any issues that arise.

3. Implementation Guide Publication

Once we are happy with the results, we can generate the Implementation Guide. The following command will generate all the required HTML files with the IG content and put them to ig-publisher/output folder:

• publish-ig.md

Generate and publish the complete IG:

claude
> /publish-ig

4. Review Published IG

Once the IG is generated, we can view it in the browser.

• view-ig.md

claude  
> /view-ig

5. (Optional) Load the IG into Aidbox

Once the IG is generated, you can load it into Aidbox to start using it in your projects.

Navigate to the Aidbox UI -> FAR. Click "Import package" button and select the ig-publisher/output/package.tgz file.

AI Assistant Configuration

Apart from Claude commands we used above, there's a general configuration file for the Claude in the CLAUDE.md file.