Effective Prompting

To get the best results from Codegen, treat it like a skilled teammate: provide clear, specific instructions and sufficient context. Vague requests lead to ambiguous outcomes.

Codegen is based on Anthropic’s Claude 3.7. You can prompt it similarly to ChatGPT or other LLM-based assistants, but with access to powerful development tools.

The Core Principle: Specificity

Instead of “Fix the user service,” try:

In the my-web-app repo (PR #42), refactor the UserService class in src/services/user.ts to use the UserRepository pattern shown in ProductService/ProductRepository.

If there are specific implementation details you want included, make sure to specify. For example:

Ensure all tests in tests/services/user.test.ts pass and add new tests for the repository with 90%+ coverage. Update the diagram in docs/architecture/user-service.md.

Elements of a Strong Prompt

1. Scope: What repository, branch, or files are involved? (e.g., my-web-app repo, PR #42, src/services/user.ts)
2. Goal: What is the high-level objective? (e.g., Refactor UserService, improve testability)
3. Tasks: What specific actions should the agent take? Use a numbered or bulleted list for clarity. (e.g., Extract logic to UserRepository, use dependency injection, update tests, update diagram)
4. Context/Patterns: Are there existing patterns, examples, or documentation to reference? (e.g., ProductService, ProductRepository)
5. Success Criteria: How will you know the task is done correctly? (e.g., Tests pass, 90%+ coverage, diagram updated)

Platform-Specific Guidance

Slack Integration

When prompting Codegen in Slack:

• Use threads for complex, multi-step requests to keep context organized
• Tag specific repos early in the conversation: “In the frontend repo…”
• Reference PR numbers directly: “Review PR #123 and suggest improvements”
• Ask for status updates on long-running tasks: “What’s the progress on the refactoring?”

Example Slack prompt:

@codegen In the `api-server` repo, can you:
1. Add input validation to the `/users` endpoint
1. Use the same validation pattern as `/products`
1. Add tests covering edge cases
1. Update the OpenAPI spec

Let me know when you have a PR ready! 🚀

Linear Integration

When working with Linear issues:

• Reference issue numbers for context: “This relates to CG-1234”
• Break down large tasks into sub-issues when appropriate
• Specify acceptance criteria clearly in the issue description
• Use @codegen to assign implementation tasks directly

Example Linear prompt:

@codegen Please implement the user authentication feature described in this issue.

Requirements:
- JWT-based auth with refresh tokens
- Follow the security patterns in `auth/oauth.ts`
- Add middleware for protected routes
- Include comprehensive tests
- Update the API documentation

This should integrate with the existing user management system.

GitHub Integration

When requesting PR reviews or code changes:

• Link to specific files and line numbers when possible
• Reference related issues or previous PRs for context
• Specify review criteria: security, performance, maintainability
• Request specific types of feedback: “Focus on error handling”

Example GitHub prompt:

@codegen Please review this PR focusing on:
1. Security implications of the new auth flow
1. Performance impact of the database queries
1. Test coverage for edge cases

Also check if the error handling follows our patterns in `utils/errors.ts`.

Common Task Types

Code Review

Review PR #456 in the `backend` repo and check for:
- SQL injection vulnerabilities
- Proper error handling
- Performance bottlenecks
- Test coverage gaps
- Documentation updates needed

Bug Fixing

There's a memory leak in the `data-processor` service when handling large files.
- Investigate the issue in `src/processors/file-handler.ts`
- Look at similar fixes in `image-processor.ts`
- Add monitoring to prevent future occurrences
- Include regression tests

Feature Development

Implement a real-time notification system:
- Use WebSockets for live updates
- Follow the event pattern in `events/user-events.ts`
- Add rate limiting (max 10 notifications/minute)
- Support both browser and mobile clients
- Include end-to-end tests

Refactoring

Refactor the payment processing module to improve testability:
- Extract external API calls into separate services
- Add dependency injection
- Follow the repository pattern used in `user-service`
- Maintain backward compatibility
- Achieve 95%+ test coverage

Advanced Techniques

Providing Context Effectively

When working with large codebases:

In the `e-commerce` monorepo, I need to add a new payment method.
Context:
- Existing payment methods are in `src/payments/methods/`
- The `PaymentProcessor` interface is in `src/payments/types.ts`
- Configuration is handled in `config/payments.json`
- Tests follow the pattern in `tests/payments/stripe.test.ts`

Please implement Apple Pay support following these existing patterns.

Iterative Prompting

Build on previous work:

Following up on the authentication PR you created:
- The security team wants 2FA support added
- Use the same JWT structure but add a `requires_2fa` claim
- Integrate with the existing `TwoFactorService`
- Update the login flow to handle 2FA challenges

Handling Complex Dependencies

For interconnected changes:

I need to update the user model across multiple services:
1. Add `preferences` field to User model in `user-service`
1. Update the GraphQL schema in `api-gateway`
1. Modify the frontend components in `web-app/src/components/user/`
1. Add database migration scripts
1. Update all related tests

Please coordinate these changes and create PRs in the correct order.

Troubleshooting Common Issues

”I don’t have enough context”

Problem: Codegen asks for more information Solution: Provide file paths, existing patterns, and specific requirements upfront

”The changes broke existing functionality”

Problem: Modifications caused test failures Solution: Always specify which tests should continue passing and request regression testing

”The implementation doesn’t match our patterns”

Problem: Code doesn’t follow team conventions Solution: Reference specific examples of preferred patterns in your codebase

”The task is too large”

Problem: Request is overwhelming or unclear Solution: Break down into smaller, specific tasks with clear dependencies

Best Practices

Be Specific

Include file paths, function names, and exact requirements rather than general descriptions.

Provide Examples

Reference existing code patterns, similar implementations, or desired outcomes.

Set Success Criteria

Define what “done” looks like: passing tests, performance metrics, or specific functionality.

Consider Dependencies

Mention related systems, APIs, or components that might be affected by changes.

Clear, detailed prompts empower Codegen agents to deliver accurate results faster, significantly streamlining your workflow. Remember that Codegen has access to your entire codebase and can understand complex relationships between files.

Getting Help

If you’re unsure how to structure a prompt for your specific use case:

• Start with a simple request and iterate based on the results
• Ask Codegen to suggest how to break down complex tasks
• Reference the capabilities documentation to understand available tools
• Check out real examples in our use cases section