AWS Logo
Menu

Amazon Q Developer Onboarding

The Amazon Q guide shows how to set up this AI coding assistant safely, covering security practices and tips to make it understand your projects better.

amazonqamazonqcliamazonqdeveloper
aidin
Amazon Employee
Published May 6, 2025

Amazon Q Developer Onboarding

Activation Steps (for an account admin in the management account)

  1. Enable IAM Identity Center in the management AWS account - Amazon Q Developer requires an instance of IAM Identity Center to be enabled in any non-opt-in AWS Region. This instance can be either an organization or account variant, though organization is recommended. This allows workforce users to sign in and use Q Developer.
  2. Create a group for Amazon Q Developer Pro users and add users to this group by selecting them from your directory.
  3. Subscribe group or users to Amazon Q Developer Pro in a management account.
  4. Extend the session duration for Amazon Q Developer if needed - If your developers use Amazon Q Developer as part of an integrated development environment (IDE), you can set the session duration for Amazon Q Developer to 90 days. Depending on when you enabled IAM Identity Center, extended session duration for Amazon Q Developer might be enabled by default.
  5. Share the Start URL with developers.
Subscribe group to Amazon Q Developer
Extend duration
Start URL

Installation

Installing Amazon Q Developer in IDE

To set up Amazon Q Developer in your integrated development environment (IDE), complete the following steps. After installing the Amazon Q extension or plugin, authenticate through IAM Identity Center.
After your identity has been subscribed to Amazon Q Developer Pro, complete the following steps to authenticate:
  1. Install the Amazon Q extension in VS Code.
  2. Choose the Amazon Q icon in your IDE. The icon will be on the side of the interface by default.
  3. Choose Use with Pro license.
  4. Fill in the Start URL that your administrator got from the Amazon Q subscription console.
  5. Fill in the AWS Region in which your administrator set up your IAM Identity Center instance.
  6. Choose Continue. The focus will switch to your web browser.7
  7. Follow the instructions in your browser to authenticate with IAM Identity Center, and then return to the IDE.
  8. To begin using Amazon Q, choose the Amazon Q icon to chat with Amazon Q, or choose Amazon Q from the navigation bar at the bottom of your IDE.
IDE
Pro
Start

Installing Amazon Q for Command Line

  1. You can install Amazon Q for command line for macOS by downloading the application or by using Homebrew. After installing Amazon Q for command line for macOS, you can enable SSH integration to be able to use autocomplete for over 500 command line tools.
  2. To install Amazon Q for command line for macOS:
  3. Download Amazon Q for command line for macOS.
  4. (Optional) Verify the downloaded file for Amazon Q for command line on macOS.
  5. Double-click on the downloaded .dmg file, and drag the app into your applications folder.
  6. Authenticate with IAM Identity Center using the start URL given to you by your account administrator.
  7. Follow the instructions to install the shell integrations, and to grant macOS accessibility permissions.
CLI

Recommendation - Install Amazon Q Developer in both your IDE and terminal command line. You can also open Amazon Q Developer in your IDE terminal.

Q in IDE and CLI

How to use?

Amazon Q Developer provides an enhanced CLI agent within the Amazon Q command line interface (CLI). This agentic experience delivers a dynamic, interactive coding experience that works collaboratively with you, iteratively making changes based on your feedback. Amazon Q Developer uses information from your CLI environment to help you read and write files locally, query AWS resources, write code, and automatically debug issues.
How to use it

Key Capabilities

  • File System Access: Read and write files in your local environment
  • AWS Integration: Query and manage AWS resources directly
  • Code Generation: Create applications from scratch or enhance existing code
  • Troubleshooting: Identify and fix issues in your deployments
  • Infrastructure as Code: Generate and optimize cloud infrastructure templates

Development Use Cases

Application Creation from Scratch

You can ask Amazon Q to build complete applications based on your requirements.
For example - Help me build a serverless application for event registration with the following requirements:
  • Application requirements:
    • User registration form with name, email, and event selection
    • Email confirmation to users after registration
    • Admin dashboard to view and manage registrations
    • Secure authentication for admin access
  • Architecture and technology:
    • Frontend: React.js with AWS Amplify for hosting and authentication
    • Backend: AWS Lambda functions with API Gateway
    • Database: DynamoDB for storing registration data
    • Authentication: Amazon Cognito for user management
    • Notifications: Amazon SES for email confirmations
    • Infrastructure as Code: AWS CDK, SAM template, or Terraform
Amazon Q will provide a step-by-step implementation plan following best practices.

Code Documentation, Transformation

Amazon Q Developer enhances your coding workflow by generating comprehensive code documentation and performing intelligent code transformations. It automatically creates detailed comments throughout your codebase and enables sophisticated refactoring between languages or frameworks while preserving functionality and implementing modern programming paradigms and best practices.
Access these capabilities by opening your project in Visual Studio Code with the Amazon Q extension or by launching q chat directly in your terminal from your project directory. Amazon Q will analyze your code structure and suggest targeted improvements based on context.
Beyond basic documentation, Amazon Q can create rich architectural documentation, including detailed data flow diagrams and system architecture overviews, seamlessly integrated into your project's README files or dedicated documentation sections.
Examples:
  • Analyze my current codebase and add comprehensive documentation including function descriptions, parameter explanations, and usage examples
  • Add new logic to allow users to select a specific language from the website that persists across sessions
  • Convert this codebase from Python 3.8 to Python 3.12, updating deprecated functions
  • Transform this Python application to Go, maintaining the same functionality
  • Review my project for AWS best practices to ensure security and cost effectiveness
Analyze

Code Test (unit test or integration test)

Generate comprehensive test suites by asking Amazon Q to create targeted unit or integration tests for your code. Simply request: "Write unit tests for my authentication service" or "Create integration tests for the order processing workflow from checkout to confirmation." Customize your testing approach by specifying preferences for testing frameworks (Jest, PyTest, JUnit, etc.), coverage requirements, and particular test scenarios including edge cases.
Amazon Q intelligently analyzes your codebase structure and dependencies to generate well-structured tests that follow language-specific best practices, ensuring thorough validation of your application's functionality while maintaining readability and maintainability.

Collaborative Workflow

After asking Amazon Q to perform a task:
  1. Q will read your current file system and begin working on your request
  2. Q might create new files or suggest improvements to existing ones
  3. Review Q's work and approve it by typing 'y' or 'yes'
  4. Provide additional feedback for further improvements
  5. Continue collaborating until the task meets your requirements

Specialized Use Cases

Database Operations

Amazon Q can help with database-related tasks:
  • Write a SQL query to get customer names for the North America region
  • Review my existing DynamoDB table and suggest the optimal partition key
When you've provided AWS credentials, Q can query or scan your DynamoDB tables to analyze your data structure and recommend optimizations for performance and cost.
db1
db2

Infrastructure as Code (IaC)

Amazon Q supports popular IaC tools including AWS CloudFormation, Terraform, AWS CDK, and Pulumi:
  • Design a serverless architecture for my web application
  • Write Terraform code for a multi-region AWS deployment with high availability
  • Create an ECS cluster with auto-scaling and load balancing
  • Optimize my CloudFormation template for better security posture
Q will generate infrastructure code following cloud best practices for security, scalability, and cost optimization, and can help with deployment steps and troubleshooting.

Deployment Troubleshooting

When encountering issues with deployed applications, Amazon Q can:
  1. Investigate: Retrieve logs, examine configurations, and analyze related resources
  2. Diagnose: Identify error patterns and root causes
  3. Resolve: Implement fixes automatically
Example scenario:
If you ask: "My Lambda function 'order-processing-service' is failing. Can you help troubleshoot it?"
Amazon Q will:
  • Retrieve CloudWatch logs to identify error patterns
  • Examine function configuration and permissions
  • Check related resources (IAM, environment variables, dependencies)
  • Analyze performance metrics
Q will then provide a comprehensive analysis and implement fixes such as:
  • Updating code to handle malformed input
  • Adding required IAM permissions
  • Implementing retry logic with exponential backoff
  • Adjusting timeout settings and memory allocation

Working with Specialized Requirements

For unique challenges:
  1. Provide detailed context about your specialized use case
  2. Share relevant documentation or specifications
  3. Explain what makes your use case unique
  4. Describe previous approaches you've tried
  5. Specify your technical environment and limitations
Amazon Q will work collaboratively with you, asking clarifying questions to better understand your needs. If the initial solution doesn't fully address your requirements, you can refine it by saying "This needs to account for [specific requirement]."

Security Best Practices

Why Security Matters with Amazon Q

Amazon Q is a powerful AI assistant that can modify your system and AWS resources. Understanding the security implications and following best practices is essential to ensure you're using these capabilities safely and effectively.

General Security Considerations

Amazon Q provides powerful capabilities that can modify your system and AWS resources. Understanding security implications and following best practices helps you use these capabilities safely.
  • Unintended system changes: Amazon Q may interpret your requests in unexpected ways, leading to unintended modifications.
  • AWS resource modifications: Resources could be created, modified, or deleted, potentially affecting production environments or incurring costs.
  • Data loss: Commands that delete or overwrite files could result in data loss.
  • Security vulnerabilities: Commands might compromise system security if not properly reviewed.
AWS recommends against using /tools trustall or /acceptall mode in production environments or when working with sensitive data or resources. You are responsible for all actions performed by Amazon Q when these modes are enabled.

Restricting File Access (Command Line)

By default, Amazon Q can read files without asking for permission each time (fs_read is trusted by default). For sensitive environments, you can restrict this behavior:
Amazon Q> /tools untrust fs_readWith this setting, Amazon Q will ask for your explicit permission before reading any file. This gives you granular control over which files Amazon Q can access during your session.

Managing Tool Permissions

/tools untrust fs_read
Restricts Amazon Q's ability to read files without explicit permission. With this setting, Amazon Q will ask for your permission before reading any file.
Requires explicit permission before Amazon Q can make AWS API calls. This adds an extra layer of security when working with AWS resources.
Resets all tool permissions to their default settings. Use this after enabling trustall to return to safer default permissions.
Enables all tools without requiring permission for each use. Warning: Only use in development environments, never in production!
If you must use /tools trustall or /acceptall for specific workflows, follow these safety practices to minimize risks:
  • Only use in development or testing environments, never in production.
  • Enable /tools trustall only for specific tasks, then immediately disable it using `/tools reset` to return to default permissions.
  • Back up important data before enabling /tools trustall.
  • Use AWS credentials with minimal permissions when /tools trustall is enabled.
  • Carefully monitor all actions Amazon Q takes while /tools trustall is enabled.

Project-Level Security

Using Project Rules

Amazon Q supports project-level rules that can define security guidelines and restrictions. These rules are defined in Markdown files in the .amazonq/rules directory of your project.
  • Which directories Amazon Q should avoid accessing
  • Security requirements for generated code
  • Coding standards and best practices

Additional Security Measures

For environments with highly sensitive information, consider these additional measures:
  • Use Amazon Q in a dedicated development environment that doesn't contain sensitive credentials or data.
  • Store sensitive files outside your project directories or in locations with restricted permissions.
  • Use environment variables for sensitive values instead of hardcoding them in files.
  • Consider using /tools untrust use_aws to require explicit permission before making AWS API calls.

Using Profiles and Context for Better Responses

Context files contain information like development rules, project details, or coding standards that Amazon Q uses to provide more relevant and tailored responses.
When you add new profiles, they will have their own unique workspace context, allowing you to specify patterns of files that make that profile behave and interact in ways unique to your workflow and processes.
profile

Creating Context Files

Context files are markdown files that contain information you want Amazon Q to consider during your conversations. These can include project requirements, coding standards, development rules, or any other information that helps Amazon Q provide more relevant responses. For how to create a context file, please refer to the documentation.
q chat >
/context add --global coding-standards.md
Added 1 path(s) to global context.

Using Context Hooks

Context hooks are a feature in Amazon Q Developer CLI that you can use to automatically inject context into your conversations with Q Developer. Instead of manually adding context with the /context command, context hooks run commands and include their output as context.

Git Status

Add a hook to show git status with each prompt:
This hook runs the git status --short command before each prompt and includes the output in your conversation with Q Developer. This helps Q Developer understand the current state of your git repository when you ask questions about version control or need help with git commands.

Project Information

Add a hook to show project information at the start of a conversation:
This hook runs once at the beginning of your conversation and includes the current project name in the context. This helps Q Developer provide more relevant responses that are specific to your project.
Tip: You can expand this hook to include more project information, such as the programming language, framework, or project structure.

Managing Token Usage

Monitor and manage your token usage with the /usage command to optimize your conversations with Amazon Q.
Current context window (5720 of 200k tokens used)
████████████████████████████████████████████████████████████████████████████████ 2.86%
█ Context files: ~5720 tokens (2.86%)
█ Q responses: ~0 tokens (0.00%)
█ Your prompts: ~0 tokens (0.00%)
💡 Pro Tips:
Run /compact to replace the conversation history with its summary
Run /clear to erase the entire chat history
Run /context show to see tokens per context file

Adding workspace context to Amazon Q Developer chat in the IDE

When you chat with Amazon Q in the integrated development environment (IDE), you can add @workspace to your question to automatically include the most relevant chunks of your workspace code as context. Amazon Q Developer determines relevance based on an index that is updated periodically.
With workspace context, Amazon Q has enhanced capabilities, including locating files, understanding how code is used across files, and generating code that leverages multiple files, including files that aren’t opened.
To enable, follow steps captured in the documentation link.

Amazon Q Developer other features

Amazon Q Developer is available across AWS environments and services, and also as a coding assistant in third party IDEs.
Many of Amazon Q Developer’s capabilities exist in a chat interface, where you can use natural language to ask questions about AWS, get help with code, explore resources, or troubleshoot. When you chat with Amazon Q, Amazon Q uses the context of your current conversation to inform its responses. You can ask follow-up questions or refer to its response when you ask a new question.
Other Amazon Q Developer features are available as a part of your workflows in AWS service consoles and supported IDEs. The following sections explain the different features of Amazon Q Developer that you might encounter across your AWS experience.
For more information, check the documentation

Reporting issues

You can report issues with Amazon Q for command line directly from the command line or through GitHub.

To report an issue using the command line
  1. Open your terminal or command prompt.
  2. Run q issue
  3. Follow the prompts to describe the issue you're experiencing.
  4. Review the information that will be included in your report, including system information and logs.
  5. Confirm to submit the issue report.
The issue report will be sent to the Amazon Q team for investigation.
To report an issue on GitHub
  1. Visit the Issues page on the GitHub repository.
  2. Click "New issue".
  3. Fill out the issue template with details about the problem you're experiencing.
  4. Submit the issue.

Conclusion

Amazon Q Developer helps you code faster and better. This guide shows you how to set it up safely, protect your systems, and make it understand your projects. By following these simple steps, your team can work smarter while keeping everything secure.

References

Any opinions in this post are those of the individual author and may not reflect the opinions of AWS.

Comments