Skip to content
ReArch Docs

Lesson 4: Best Practices

Writing Effective Task Descriptions

Section titled “Writing Effective Task Descriptions”

The single biggest factor in agent output quality is how you describe the task. Follow these guidelines:

Be Specific, Not Vague

Section titled “Be Specific, Not Vague”
VagueSpecific
”Fix the search""Fix: search results do not include partial matches. Currently searching for ‘react’ does not return ‘react-dom’. Update the search logic in src/utils/search.ts to support substring matching."
"Add tests""Write unit tests for src/services/auth.ts covering login(), logout(), and refreshToken(). Include tests for expired tokens and invalid credentials."
"Improve performance""The product list page renders slowly with 500+ items. Add virtualised scrolling using react-window to src/components/ProductList.tsx.”

Include Context

Section titled “Include Context”
  • Reference specific files the agent should look at or modify
  • Mention the framework or library conventions to follow
  • Link to related issues or PRs if relevant

Set Constraints

Section titled “Set Constraints”
task:
  description: "Refactor auth middleware to use JWT verification"
  constraints:
    files:
      - src/middleware/auth.ts
      - src/utils/jwt.ts
    branch: refactor/jwt-auth
    tests: true
    no_new_dependencies: true

Constraints prevent the agent from going off track. Use no_new_dependencies: true to avoid surprise additions to package.json.

Project Structure

Section titled “Project Structure”

Agents work best when your project has a clear, consistent structure:

Consistent Naming

Section titled “Consistent Naming”
# Good — predictable patterns
src/
  components/
    UserCard/
      UserCard.tsx
      UserCard.test.tsx
      UserCard.module.css
  services/
    user.service.ts
    billing.service.ts


# Hard for agents — inconsistent patterns
src/
  components/
    user-card.jsx
    BillingForm.tsx
    loginModal/modal.js
  api/
    Users.ts
    billing_api.ts

Documentation as Context

Section titled “Documentation as Context”

Keep a short ARCHITECTURE.md in your project root. The agent reads it automatically:

# Architecture


## Stack


- Next.js 14 (App Router)
- TypeScript strict mode
- Tailwind CSS
- PostgreSQL via Prisma ORM


## Conventions


- Components use PascalCase directories with co-located tests
- API routes follow REST conventions
- All database queries go through Prisma (no raw SQL)
- Use `zod` for all input validation

This 10-line file dramatically improves agent output quality because it provides immediate architectural context.

Security Considerations

Section titled “Security Considerations”

Secrets

Section titled “Secrets”

ReArch never has access to your secrets unless you explicitly provide them. However, keep these practices:

  • Use .env files for secrets and ensure they are in .gitignore
  • Never put API keys in task descriptions
  • Use environment variables in configuration, not hard-coded values

Code Review

Section titled “Code Review”

Always review agent-generated code before merging. Pay attention to:

  • Dependencies: Did the agent add new packages? Are they trustworthy?
  • Security: Does the code handle user input safely? SQL injection, XSS, etc.
  • Scope: Did the agent modify files outside the requested scope?
  • Tests: Do the tests actually test meaningful behaviour, or are they just passing stubs?

Access Control

Section titled “Access Control”

In team environments, configure role-based access:

.rearch/config.yaml
access:
  agents:
    - name: feature-agent
      repos: ["frontend", "docs"]
      branches: ["feat/*", "fix/*"]
      # Cannot push to main
    - name: release-agent
      repos: ["*"]
      branches: ["release/*"]

Performance Tips

Section titled “Performance Tips”
  1. Smaller tasks are better — Break large features into multiple focused tasks
  2. Provide examples — If you want a specific code style, show it in the task description
  3. Use pipelines — Custom pipelines for different task types (feature, bugfix, refactor) improve consistency
  4. Iterate — Do not try to get everything perfect in one shot. Review, provide feedback, let the agent improve.

Course Summary

Section titled “Course Summary”

Congratulations — you have completed the Getting Started with ReArch course. You now know:

  • What ReArch is and how its agents, pipelines, and tasks work
  • How to install and configure your workspace
  • How to create, monitor, and review AI-powered tasks
  • Best practices for writing effective tasks and maintaining security
Section titled “Recommended Next Steps”