Stop Comparing Codex, Claude, and Cursor—Java Teams Should Focus on These Four AI Assets

1. Model changes vs. stable project rules

Developers repeatedly repeat the same requirements (Java version, layered architecture, no direct DB access, etc.) for each AI tool, which wastes context and time. The solution is to store stable project guidelines in an AGENTS.md file and define reusable Skills, allowing any AI agent to understand and follow the rules without re‑explaining them.

# AGENTS.md
## 技术栈
- Java 21
- Spring Boot 3.5
- Maven
- PostgreSQL
- Flyway
- JUnit 5
- Testcontainers
## 架构规则
- Controller 只能调用 Application Service
- Controller 禁止直接调用 Repository
- 核心业务逻辑必须放在 Domain 或 Service 层
- Entity 不允许直接作为接口返回值
- 新增接口必须定义 Request 和 Response DTO
- 数据库结构变更必须使用 Flyway
## 安全规则
- 禁止修改 application-prod.yml
- 禁止输出密码、Token 和数据库连接信息
- 禁止关闭权限校验
- 禁止将用户敏感字段写入日志
- 未经人工确认不得执行 git push
## 验收规则
1. ./mvnw spotless:check
2. ./mvnw test
3. ./mvnw verify
如果命令失败，必须读取完整日志并修复，不能跳过测试。

This file does not produce business functionality but guides agents on what can be written, what cannot, and when a task is truly complete.

2. Rules solve "what not to do", Skills solve "how to do it"

Rules capture long‑term constraints, while Skills encapsulate multi‑step procedures such as adding a CRUD module, checking transactions, or analyzing logs. Each AI tool (Codex, Claude Code, Cursor, ZCode) supports Skills via SKILL.md files, reducing repeated prompts.

.ai/
└── skills/
    └── spring-api/
        ├── SKILL.md
        ├── references/
        │   ├── response-format.md
        │   └── exception-rules.md
        └── scripts/
            └── verify-api.sh

Example SKILL.md for a Spring Boot API:

---
name: spring-api
---
# Spring Boot API development process
## Step 1: Analyze existing structure
Read:
- pom.xml
- AGENTS.md
- Similar module Controller
- Similar module Service
- Global exception handler
- Unified response format
## Step 2: Output implementation plan
List files to add/modify, DB changes, permissions, tests.
## Step 3: Implement respecting constraints
- Entity not returned directly
- Request DTO validation
- Service handles transactions
- Controller contains no business logic
- Exceptions go to handler
## Step 4: Verify
```bash
bash .ai/skills/spring-api/scripts/verify-api.sh
```

3. Create specialized Agents instead of a single "all‑purpose" Agent

Separate agents by role: an Architecture Agent (read‑only analysis), a Development Agent (writes code), a Test Agent (runs tests and analyzes failures), and a Security Review Agent (checks permissions, SQL injection, secret leaks, etc.). This avoids conflicts and ensures each agent enforces its own constraints.

---
name: java-security-reviewer
description: Review security, permissions, and data risks in Spring Boot code
---
You are a Java security review Agent.
Only read code and Git diff; do not modify files.
Check for:
1. Missing permission annotations
2. Horizontal privilege escalation
3. Potential tenant‑bypass SQL queries
4. Sensitive data in logs
5. Transaction failures
6. Missing request validation
7. Internal exception exposure
8. Risky DB migrations
Output format:
- Critical issues
- General issues
- Recommendations
- Suggested tests

4. Hooks enforce the final safety net

Hooks turn suggested actions into mandatory steps, such as running code formatters, preventing dangerous commands, or executing verification scripts before an agent can finish.

#!/usr/bin/env bash
set -euo pipefail
echo "Check uncommitted changes"
git diff --check
echo "Check production config changes"
if git diff --name-only | grep -q "application-prod"; then
  echo "Production config changed – aborting"
  exit 1
fi
echo "Check DB migrations"
if git diff --name-only | grep -q "src/main/resources/db/migration"; then
  echo "DB migration detected – requires extra review"
fi
echo "Run Maven verification"
./mvnw verify

Another hook blocks high‑risk commands:

#!/usr/bin/env bash
COMMAND="${1:-}"
case "$COMMAND" in
  *"git push --force"*|*"rm -rf"*|*"DROP TABLE"*|*"TRUNCATE TABLE"*)
    echo "High‑risk command detected – blocked"
    exit 1
    ;;
esac
exit 0

5. Why this model fits Java

Java projects have clear layering, strict typing, stable build tools, and extensive testing—attributes that make them ideal for codifying into Rules, Skills, and Hooks. Translating implicit conventions into explicit assets improves AI reliability.

6. Expose Spring services to agents via MCP

Spring AI 2.0 allows Java services to be annotated as MCP tools, enabling agents to call them safely. Example:

@Component
@RequiredArgsConstructor
public class OrderMcpTools {
  private final OrderQueryService orderQueryService;

  @McpTool(name = "get_order_detail", description = "Query order details by ID")
  public OrderDetailResponse getOrderDetail(Long orderId) {
    return orderQueryService.getOrder(orderId);
  }
}

Only read‑only or well‑guarded services should be exposed; write‑heavy operations need authentication, validation, auditing, and manual approval.

7. Build an "AI Engineering Adaptation Layer"

Maintain tool‑agnostic assets under .ai (Rules, Skills, Agents) and separate adapter directories for each tool ( .codex, .claude, .cursor). This lets teams switch models without losing accumulated engineering knowledge.

project-root/
├── AGENTS.md
├── CLAUDE.md
├── .ai/
│   ├── standards/
│   │   ├── java-style.md
│   │   ├── architecture.md
│   │   ├── security.md
│   │   └── testing.md
│   ├── skills/
│   │   ├── spring-api/
│   │   ├── database-migration/
│   │   └── incident-analysis/
│   ├── agents/
│   │   ├── architect.md
│   │   ├── developer.md
│   │   ├── tester.md
│   │   └── security-reviewer.md
│   └── scripts/
│       ├── verify.sh
│       ├── check-secrets.sh
│       └── block-dangerous-command.sh
├── .codex/
├── .claude/
└── .cursor/

8. The future of AI‑assisted development

As AI tools become more powerful, the risk of uncontrolled changes grows. Teams should first codify project rules, then capture repeatable processes as Skills, create role‑specific Agents, and finally enforce Hooks for verification. Models and editors may change, but the engineered standards, testing, security, and delivery processes must remain in the repository as the true valuable assets for Java teams.