AIDLC Code Reviewer

July 6, 2026 · View on GitHub

Agent-native code review toolkit for AIDLC projects. It combines deterministic local static analysis with assistant-driven review phases for critical technical findings, code structure critique, and business logic checkpoints.

This repository is intended to run inside an AI coding assistant. The assistant does the reasoning; the local Python tools do discovery, static tool execution, normalization, scoring, and Markdown/HTML report generation.

Requirements

  • Bash-compatible shell to run install.sh
  • Python 3.10+ available as python3
  • Optional static analysis tools such as ruff, mypy, and bandit; missing tools are reported as warnings and do not block the review

Layout

.
├── common/
│   ├── methodology/          # Shared review instructions
│   ├── tools/                # Deterministic Python stdlib tools
│   └── review-config.yaml    # Shared settings and tool toggles
├── claude/                   # Claude Code packaging
├── codex/                    # Codex packaging
├── copilot/                  # GitHub Copilot packaging
├── kiro/                     # Kiro packaging
├── tests/                    # Tool and installer tests
└── install.sh

Quick Start

Clone this toolkit once:

git clone https://github.com/aws-samples/sample-aidlc-code-reviewer.git ~/tools/sample-aidlc-code-reviewer

From the project you want to review, install the assistant integration:

cd /path/to/your/project
~/tools/sample-aidlc-code-reviewer/install.sh --ide claude

Use the assistant you want:

/path/to/sample-aidlc-code-reviewer/install.sh --ide claude
/path/to/sample-aidlc-code-reviewer/install.sh --ide kiro
/path/to/sample-aidlc-code-reviewer/install.sh --ide copilot
/path/to/sample-aidlc-code-reviewer/install.sh --ide codex

Then restart or reload the assistant session if that platform requires it, and ask:

Run AIDLC code review on ./src

The installer reads files from the cloned toolkit and writes assistant config into the current working directory by default. Run it from the project you want to review, not from the toolkit repo.

You can also ask your assistant to install it from inside the target project:

Run /path/to/sample-aidlc-code-reviewer/install.sh --ide claude, then tell me what was installed.

Platform Setup

Run the install command from the project root that should receive the assistant configuration.

AssistantInstall commandWhat to do after install
Claude Code/path/to/sample-aidlc-code-reviewer/install.sh --ide claudeRestart the Claude Code session, then run /code-review or ask to review code.
Kiro/path/to/sample-aidlc-code-reviewer/install.sh --ide kiroAsk Kiro to review code, or switch to /agent code-reviewer.
GitHub Copilot/path/to/sample-aidlc-code-reviewer/install.sh --ide copilotUse Copilot Chat agent mode and run /code-review.
Codex/path/to/sample-aidlc-code-reviewer/install.sh --ide codexAsk Codex to review code. If AGENTS.code-reviewer.md was created, merge its AIDLC section into AGENTS.md.

Default installed paths:

  • Claude Code: .claude/skills/code-review/, .claude/code-reviewer/, .claude/agents/code-*.md
  • Kiro: .kiro/code-reviewer/, .kiro/steering/code-review.md, .kiro/agents/code-reviewer.json
  • GitHub Copilot: .github/code-reviewer/, .github/prompts/code-review.prompt.md, .github/copilot-instructions.md
  • Codex: .codex/code-reviewer/ plus AGENTS.md, or AGENTS.code-reviewer.md when a non-toolkit AGENTS.md already exists

Preview operations without writing files:

/path/to/sample-aidlc-code-reviewer/install.sh --ide codex --dry-run

Re-running the installer updates the toolkit files for that assistant. For Codex, an existing non-toolkit AGENTS.md is preserved and the installer writes AGENTS.code-reviewer.md for you to merge. For the other assistants, review --dry-run first if your project already has files at the listed install paths.

Install to a custom assistant config directory:

/path/to/sample-aidlc-code-reviewer/install.sh --ide claude --dest ~/.claude

What Users Should Edit

For normal setup and static tool configuration, edit only the reviewer configuration file. Do not change copied tool, methodology, prompt, skill, or agent files just to configure which static analyzers run.

Before installation, change the shared defaults in the toolkit repo:

  • common/review-config.yaml

Then re-run the installer from the target project:

/path/to/sample-aidlc-code-reviewer/install.sh --ide <claude|kiro|copilot|codex>

After installation, change only the installed config file for that assistant:

  • Claude Code: .claude/code-reviewer/review-config.yaml
  • Kiro: .kiro/code-reviewer/review-config.yaml
  • GitHub Copilot: .github/code-reviewer/review-config.yaml
  • Codex: .codex/code-reviewer/review-config.yaml

Use review-config.yaml for:

  • Choosing which supported static analyzers the reviewer should try to run in enabled_tools.
  • Keeping supported-but-disabled analyzers in optional_tools as a reminder of tools the reviewer knows how to run.
  • Changing ignored files/directories, file size limits, severity threshold, review phases, and report path defaults.

Do not edit these installed files for normal configuration:

  • Copied static tool implementations under .claude/skills/code-review/tools/, .kiro/code-reviewer/tools/, .github/code-reviewer/tools/, or .codex/code-reviewer/tools/.
  • Copied methodology files under .claude/code-reviewer/methodology/, .kiro/code-reviewer/methodology/, .github/code-reviewer/methodology/, or .codex/code-reviewer/methodology/.
  • Assistant instruction files such as SKILL.md, code-review.md, Kiro steering files, Copilot prompt/instruction files, or generated Codex AGENTS.md content, except for the documented Codex merge step.

Adding a static analyzer that is not already supported is toolkit development, not normal setup. Make that change in this source repo, especially common/tools/run_static_tools.py, update tests and documentation, then re-run install.sh. Do not patch the installed copies under a project assistant directory.

Each install also writes install-metadata.json next to the installed review-config.yaml. Assistants can use that metadata to identify the source toolkit path, repository, and commit when a user asks to add a new analyzer.

Usage

After installing, ask the assistant to review code, for example:

Run AIDLC code review on ./src

At review start, the assistant should use the installed review-config.yaml for that project. If you want different defaults, ask the assistant to show or edit that file before it runs the review.

By default, reports go to:

aidlc-docs/review/code-review-<timestamp>.md
aidlc-docs/review/code-review-<timestamp>.html

The assistant should return a clickable Markdown link to the HTML report plus the plain report paths. If your assistant client does not render local file links, open the reported HTML path directly:

open aidlc-docs/review/code-review-<timestamp>.html

On Linux, use xdg-open <html-path>. On Windows, use start <html-path>.

Reports include:

  • A severity legend for CRITICAL, HIGH, MEDIUM, LOW, and INFO.
  • Attribution badges on findings:
    • AI: identified by assistant review.
    • Static: reported only by deterministic static analysis.
    • AI + Static: assistant finding supported by one or more static tool findings.
  • Deduplicated severity counts, quality score, and top findings. For example, one issue found by both AI review and Bandit is scored once as AI + Static, not once for each source.
  • Detailed sections for critical findings, structure critique, business logic, static analysis, and an appendix.
  • Code excerpts, related tool findings, review guidance, and risk notes when the review payload includes them.

To choose a different report location for one run, ask for it:

Run AIDLC code review on ./src and write reports to ./reports/code-review/latest

The report path is a base path without an extension; the builder writes both .md and .html.

Change Defaults

For an existing install, edit the installed review-config.yaml in the project being reviewed:

AssistantInstalled config path
Claude Code.claude/code-reviewer/review-config.yaml
Kiro.kiro/code-reviewer/review-config.yaml
GitHub Copilot.github/code-reviewer/review-config.yaml
Codex.codex/code-reviewer/review-config.yaml

Common report settings:

report_output_dir: reports/code_review
report_filename_prefix: code-review

To change the template used for future installs, edit common/review-config.yaml in this toolkit repo before running install.sh.

Static Tools

The toolkit itself requires only shell and Python 3.10+ standard library. Configured static analysis tools are optional host dependencies. The reviewer tries only the tools listed in enabled_tools; each tool is skipped with a warning if it is not installed or is not applicable to the target project.

Supported static tool adapters:

  • bandit
  • ruff
  • mypy
  • radon
  • vulture
  • eslint
  • tsc
  • semgrep
  • gitleaks
  • checkstyle
  • dotnet
  • dotnet-sonarscanner

For normal static tool changes, edit review-config.yaml as described in What Users Should Edit. The listed tools are the tool names recognized by common/tools/run_static_tools.py. If a project needs a static analyzer that is not listed here, add support in the toolkit source repo, update tests and documentation, then re-run install.sh. Do not patch the installed copies under .claude/, .kiro/, .github/, or .codex/.

Review Phases

  • Critical technical findings: computation, control flow, and data transform code that needs mandatory human attention.
  • Structure critique: logging, measurability, scalability, efficiency, complexity, and architecture structure.
  • Business logic review: formulas, eligibility rules, state transitions, pricing, temporal logic, reconciliation, and consistency issues.

Development

Run tests from the repository root:

python3 -m unittest discover -s tests

Run the deterministic tools directly:

python3 common/tools/discover_code.py --target /path/to/your/project
python3 common/tools/run_static_tools.py --target /path/to/your/project

Security

See SECURITY.md. Reports are advisory only; see LEGAL_DISCLAIMER.md.