Setting up harness for AI agents in the project

Project Structure for High-Performance AI Agents

AI agents thrive on clear, consistent project structure. Setting up a harness enables agents to understand architecture, run tests, and interact with the environment without constant hand-holding. These principles apply across tools like Claude Code, Cursor, and others.

Core Rule Configuration

Start with a single file in your project root—CLAUDE.md or its equivalent for your agent. Outline directory structure, key commands, and general development guidelines. Avoid detailed implementation instructions: code itself becomes the documentation.

Example base file:

## Structure
├── src/           — service code
├── tests/         — test suite
├── migrations/    — Alembic database migrations
└── notebooks/     — ad-hoc scripts

## Commands
- Tests: `pytest tests/ -x`
- Linter: `ruff check . --fix`
- Migrations: `alembic upgrade head`
- Run: `docker compose up`

This setup eliminates repetitive explanations of architecture and routine tasks. Enforce code standards via scripts—not manuals.

When an agent makes mistakes—analyze context. If it duplicates methods or misplaces classes, add modular rule files.

something-cool/
├── CLAUDE.md                          # general rules
├── src/
│   ├── auth/
│   │   ├── CLAUDE.md                  # SSO rules
│   │   └── ...
│   ├── billing/
│   │   ├── CLAUDE.md                  # contract-based mutations
│   │   └── ...

Signs of incomplete setup:

• Agent manually searches for modules.
• Makes basic errors in dependencies or registration.

Environment Integration via Skills

Agents don’t just work with code—they interact with logs, metrics, and databases. Use skills to integrate external services: define functions and provide executable scripts.

Skill structure:

.claude/
└── skills/
    ├── logs/
    │   ├── SKILL.md
    │   └── search_logs.py
    ├── metrics/
    │   ├── SKILL.md
    │   └── query_grafana.py
    ├── database/
    │   ├── SKILL.md

Example SKILL.md for logs:

---
name: logs
description: Search and analyze application logs
allowed-tools: Bash, Read
---

Use this script to search logs:
python .claude/skills/logs/search_logs.py --query "error" --since "1h"
python .claude/skills/logs/search_logs.py --trace-id "abc123"

Now the agent can independently gather insights and troubleshoot issues.

Cross-Repository & Team Compatibility

Share skills between projects using public marketplaces or internal solutions. This lowers the barrier for teammates.

To align different agents within a team, use rulesync—a CLI tool that generates instruction files for 25+ tools from one source.

Rulesync structure:

.rulesync/rules/
├── overview.md          # root: true
├── auth.md              # globs: ["src/auth/**"]
└── billing.md           # globs: ["src/billing/**"]

Markdown files with frontmatter:

---
root: false
globs: ["src/auth/**"]
targets: "*"
description: Rules for SSO integration
---
Rules go here

Generation:

• rulesync generate --targets "claudecode"
• rulesync generate --targets "cursor"
• rulesync generate --targets "copilot"

Result: CLAUDE.md, .cursorrules, copilot-instructions.md placed correctly.

Background Agents for Oversight

Add background agents to monitor style, structure, and dead code:

claude -p "Check style: naming, structure, dead code" \
  --allowedTools "Read,Grep,Glob"

This automates code reviews.

Key Takeaways

• Modular rules: Place CLAUDE.md in subdirectories for contextual clarity.
• Environment skills: Scripts + instructions for logs, metrics, DB access.
• Rulesync: Single source for multi-agent consistency.
• Evolution: Expand rules as errors emerge.
• Minimalism: Focus only on structure, commands—no implementation details.

— Editorial Team