Building an AI-Native Coding Project: A Practical Setup Guide for Claude Code and Cursor
Technology Enthusiast and voracious reader with a demonstrated history of working in the computer software industry. Skilled in PHP, JavaScript, NodeJS, Angular, MySQL, MongoDB, Web3, Product Development, Project Management, and Teamwork.
Modern AI coding agents are much more capable than autocomplete tools. Both Claude Code and Cursor can understand a repository, modify multiple files, execute commands, run tests, use external tools, delegate work to specialized agents, and perform iterative debugging.
The problem is that an AI agent is only as reliable as the engineering context and guardrails you give it.
A good project therefore needs more than a single instruction file.
You want a structure that answers:
What is this project?
What architecture should the AI follow?
How should code be written?
Which rules apply to backend vs frontend?
How should tests be written?
How should security be checked?
Which repetitive workflows should be reusable?
Which tasks deserve specialized agents?
Which actions should be automatically validated or blocked?
Which external systems can the AI access?
How can the same engineering standards be used by multiple AI coding tools?
This article builds that system practically for Claude Code and Cursor, using a Node.js/TypeScript application as the example.
1. The Goal: Turn a Repository into an AI-Native Development Environment
A traditional project might look like this:
project/
├── src/
├── tests/
├── package.json
├── README.md
└── .gitignore
The developer knows the architecture because they have worked on it for months.
The AI does not.
Every new session starts with limited knowledge of your project. Claude Code explicitly describes CLAUDE.md as persistent project context, while Cursor provides persistent rules and AGENTS.md for the same general purpose. (Claude)
So we introduce an AI engineering layer:
┌─────────────────────┐
│ Developer │
└──────────┬──────────┘
│
▼
┌─────────────────────┐
│ AI Agent │
│ Claude / Cursor │
└──────────┬──────────┘
│
┌─────────────────────┼─────────────────────┐
│ │ │
▼ ▼ ▼
Instructions Rules Skills
│ │ │
└─────────────────────┼─────────────────────┘
│
▼
Subagents
│
▼
MCP / Tools
│
▼
Hooks
│
▼
Code + Tests + Validation
The important idea is:
Instructions tell the AI what to do. Rules tell it how to work. Skills teach it repeatable workflows. Subagents specialize the work. Hooks enforce guardrails. MCP gives it external capabilities.
2. Claude Code vs Cursor Architecture
Although both tools solve similar problems, their configuration mechanisms are not identical.
| Capability | Claude Code | Cursor |
|---|---|---|
| Main project instructions | CLAUDE.md |
AGENTS.md / Rules |
| Project rules | .claude/rules/*.md |
.cursor/rules/*.mdc |
| Local personal instructions | CLAUDE.local.md |
User Rules |
| Skills | .claude/skills/ |
.cursor/skills/ |
| Subagents | .claude/agents/ |
.cursor/agents/ |
| Commands | .claude/commands/ |
Commands / Skills |
| Hooks | .claude/settings.json / hook configuration |
.cursor/hooks.json |
| MCP | .mcp.json / settings |
.cursor/mcp.json |
| Auto memory | Yes | Different mechanisms |
| Browser/visual workflow | Via available tools | Built into Agent workflows |
| Marketplace/plugins | Claude ecosystem | Cursor Marketplace |
| Team rules | Managed configuration | Team Rules / Customize |
Cursor currently describes Agent as an orchestration of instructions, tools and a model, with capabilities including code search, file editing, shell execution and browser interaction. (Cursor)
Cursor's current Customize system also brings plugins, skills, MCP, subagents, rules, commands and hooks together. (Cursor)
Claude Code has a comparable modular architecture around CLAUDE.md, rules, skills, subagents, hooks and MCP. (Claude)
3. The Recommended Cross-Platform Architecture
If you use both tools on the same repository, don't create two completely independent AI configurations.
Instead, separate:
Shared engineering knowledge
AGENTS.md
docs/
.cursor/rules/
from:
Claude-specific configuration
CLAUDE.md
.claude/
and:
Cursor-specific configuration
.cursor/
A practical project can therefore look like:
my-project/
│
├── AGENTS.md
├── CLAUDE.md
│
├── src/
├── tests/
├── docs/
│
├── .claude/
│ ├── rules/
│ ├── skills/
│ ├── agents/
│ └── settings.json
│
└── .cursor/
├── rules/
├── skills/
├── agents/
├── hooks.json
└── mcp.json
There is an even better approach for many teams:
AGENTS.md
│
├──────────────► Cursor
│
└──────────────► CLAUDE.md
│
└── Claude Code
Claude Code currently does not automatically treat AGENTS.md as its primary instruction file, but it supports importing it from CLAUDE.md. Its documentation explicitly recommends this pattern when a repository already uses AGENTS.md. (Claude)
For example:
# CLAUDE.md
@AGENTS.md
## Claude Code-specific instructions
Use plan mode for architectural changes.
Before modifying database migrations:
1. Inspect existing migrations.
2. Check the current schema.
3. Confirm backward compatibility.
That allows both tools to share the core engineering instructions.
4. Step One — Create the Project
Let's use a typical stack:
Backend:
Node.js
TypeScript
NestJS
PostgreSQL
Redis
Frontend:
React
TypeScript
Testing:
Jest
Playwright
Tooling:
ESLint
Prettier
GitHub Actions
Create the project:
mkdir my-project
cd my-project
git init
A basic structure:
my-project/
├── apps/
│ ├── api/
│ └── web/
│
├── packages/
│ ├── shared/
│ └── config/
│
├── docs/
│ ├── architecture/
│ ├── api/
│ └── decisions/
│
├── tests/
│
├── package.json
└── README.md
For a monorepo, the AI instructions become even more important because different applications can have different conventions.
5. Step Two — Create AGENTS.md
This is your high-level engineering contract.
Keep it concise.
Cursor recommends splitting large rule sets into focused files, and Claude Code recommends keeping CLAUDE.md concise because these instructions consume context. (Cursor)
Example:
# Project Instructions
## Project
This is a production TypeScript monorepo.
## Structure
- `apps/api` - NestJS backend
- `apps/web` - React frontend
- `packages/shared` - Shared TypeScript types
- `packages/config` - Shared configuration
- `docs` - Architecture and engineering documentation
## General Rules
- Use TypeScript.
- Do not introduce `any` unless explicitly justified.
- Reuse existing utilities before creating new ones.
- Do not duplicate business logic.
- Follow existing architectural patterns.
- Do not modify generated files manually.
- Do not modify unrelated files.
## Testing
Every behavioral change must include appropriate tests.
Before completing a task:
1. Run unit tests.
2. Run type checking.
3. Run linting.
4. Review the final diff.
## Security
Never:
- Hardcode credentials.
- Commit secrets.
- Log passwords or tokens.
- Disable authentication to make tests pass.
- Disable security controls without explicit approval.
- Trust user input without validation.
## Git
Do not:
- Force push.
- Reset unrelated changes.
- Delete user changes.
- Modify unrelated files.
## Completion
A task is complete only when:
- Implementation is complete.
- Tests pass.
- Type checking passes.
- Linting passes.
- Security implications are considered.
- Final changes are reviewed.
6. Step Three — Configure Claude Code
Claude Code's project-level instruction file can be:
CLAUDE.md
or:
.claude/CLAUDE.md
Claude's current documentation also supports:
CLAUDE.local.md
for personal project-specific instructions, which should normally be gitignored. (Claude)
I recommend:
my-project/
│
├── AGENTS.md
├── CLAUDE.md
│
└── .claude/
├── rules/
├── skills/
├── agents/
└── settings.json
And:
# CLAUDE.md
@AGENTS.md
## Claude Code Workflow
For substantial changes:
1. Explore the relevant code.
2. Identify applicable rules.
3. Create an implementation plan.
4. Implement incrementally.
5. Run tests.
6. Review the diff.
7. Report remaining risks.
Do not make broad architectural changes unless explicitly requested.
Claude Code's /init can generate or improve a starting CLAUDE.md by analyzing the repository. Current versions can also help establish skills and hooks through the newer initialization flow. (Claude)
7. Claude Code Rules
Now create:
.claude/rules/
├── architecture.md
├── coding-style.md
├── security.md
├── testing.md
├── backend.md
└── frontend.md
Claude Code supports modular .claude/rules/ files, including path-specific rules. (Claude)
For example:
---
paths:
- "apps/api/**/*.ts"
---
# Backend Rules
## Controllers
Controllers should:
- Validate input.
- Delegate business logic to services.
- Avoid database queries directly.
## Services
Services contain business logic.
## Database
Use the repository/data-access layer.
Do not access PostgreSQL directly from controllers.
This is much better than putting every rule into one giant file.
8. Cursor Rules
Cursor's equivalent is:
.cursor/rules/
with .mdc files.
For example:
.cursor/rules/
├── project.mdc
├── backend.mdc
├── frontend.mdc
├── security.mdc
└── testing.mdc
A Cursor rule:
---
description: Backend architecture rules for NestJS services
globs:
- "apps/api/**/*.ts"
alwaysApply: false
---
# Backend Architecture
Controllers should only handle:
- HTTP concerns
- Request validation
- Response mapping
Business logic belongs in services.
Database access belongs in repositories.
Do not place business logic in controllers.
Cursor supports project rules with different application modes: always, intelligently, file-specific, or manually. (Cursor)
Important
Do not use the old:
.cursorrules
for new projects.
Cursor documents .cursorrules as legacy and recommends migrating to .cursor/rules/*.mdc or AGENTS.md. (Cursor)
9. Rules vs Instructions
This distinction is extremely important.
Don't put everything into AGENTS.md.
Think about the hierarchy like this:
AGENTS.md
↓
"What is this project and what are the global rules?"
Rules
↓
"How should this particular type of code be implemented?"
Skills
↓
"How should I perform this reusable workflow?"
Subagents
↓
"Who should specialize in this task?"
Hooks
↓
"What must be validated or blocked automatically?"
For example:
AGENTS.md
Use TypeScript.
Run tests before completion.
Never commit secrets.
Security rule
Validate authentication and authorization.
Never trust request input.
Security skill
Perform a complete security audit.
Run scanners.
Trace input flows.
Generate findings.
Security subagent
Act as a senior application security engineer.
Hook
Block execution if a secret is detected.
Each mechanism has a different purpose.
10. Skills: Build Reusable AI Workflows
This is where AI project scaffolding becomes genuinely powerful.
Instead of repeatedly telling the agent:
"Review this code for security vulnerabilities."
create a reusable:
security-audit
skill.
Claude Code supports skills that package reusable workflows, instructions and resources. Cursor also implements Agent Skills as portable, version-controlled packages. (Claude)
Create:
.claude/skills/security-audit/SKILL.md
and:
.cursor/skills/security-audit/SKILL.md
The same SKILL.md can often be designed to work across both systems.
Example:
---
name: security-audit
description: Perform a production security audit of application code.
---
# Security Audit
## Objective
Identify confirmed security vulnerabilities in the requested code.
## Check
- Hardcoded secrets
- Authentication
- Authorization
- SQL injection
- NoSQL injection
- XSS
- CSRF
- SSRF
- Command injection
- Path traversal
- Unsafe deserialization
- File upload vulnerabilities
- Sensitive logging
- CORS
- Rate limiting
- Dependency vulnerabilities
## Process
1. Inspect the changed files.
2. Understand the data flow.
3. Identify trust boundaries.
4. Trace user-controlled input.
5. Review authentication.
6. Review authorization.
7. Check sensitive data handling.
8. Run available security scanners.
9. Report confirmed findings.
10. Fix confirmed vulnerabilities.
11. Re-run validation.
## Finding Format
For every issue provide:
Severity:
File:
Location:
Issue:
Attack scenario:
Recommended fix:
Cursor's current Skills implementation supports SKILL.md, optional scripts, references and assets, and automatically discovers skills from project skill directories. (Cursor)
11. Build a Security Skill
For a production Node.js application, I'd make this one of the first skills.
security-audit/
├── SKILL.md
├── scripts/
│ ├── scan-secrets.sh
│ ├── dependency-audit.sh
│ └── security-check.sh
└── references/
└── security-checklist.md
Then:
# Security Audit
Before reporting completion:
## Static checks
Run:
gitleaks detect
npm audit
eslint
## Application checks
Inspect:
Authentication
Authorization
Input validation
Database queries
File uploads
External requests
Logging
CORS
Cookies
JWT handling
This is better than relying purely on the model's reasoning.
12. Add Local Security Scanning
For example:
gitleaks detect --source .
You can also run:
npm audit
and your normal:
npm run lint
npm test
npm run typecheck
Now the architecture becomes:
AI
│
▼
Security Skill
│
├── Code analysis
├── Gitleaks
├── Dependency audit
└── Application checks
│
▼
Security findings
│
▼
Fix
│
▼
Re-run scanners
This is much safer than:
AI says "I checked security"
13. Subagents
Some tasks deserve isolated expertise.
Examples:
security-auditor
code-reviewer
debugger
test-engineer
architecture-reviewer
Claude Code supports custom subagents, and Cursor supports specialized subagents that can operate with isolated context. (Claude)
Example:
security-auditor.md
---
name: security-auditor
description: Review application code for security vulnerabilities.
---
You are a senior application security engineer.
Analyze the requested changes.
Prioritize:
1. Authentication
2. Authorization
3. Injection
4. Secrets
5. Sensitive data exposure
6. SSRF
7. XSS
8. CSRF
9. File upload security
10. Dependency vulnerabilities
Do not report theoretical issues without evidence.
For each finding provide:
- Severity
- File
- Location
- Evidence
- Exploit scenario
- Fix
14. Code Review Agent
Create:
code-reviewer.md
Example:
---
name: code-reviewer
description: Perform production-grade code review.
---
Review the current changes.
Check:
## Correctness
- Logic errors
- Edge cases
- Race conditions
## Architecture
- Layer violations
- Coupling
- Duplication
## Performance
- N+1 queries
- Excessive database calls
- Unnecessary network calls
- Memory problems
## Security
- Input validation
- Authorization
- Sensitive information
## Testing
- Missing tests
- Weak assertions
- Regression risks
Only report actionable findings.
15. Hooks: The Enforcement Layer
This is one of the most important concepts.
Instructions are not enforcement.
Claude's documentation explicitly distinguishes instructions from enforcement: CLAUDE.md guides model behavior, while hooks can be used when you need to block an action regardless of what the model decides. (Claude)
Therefore:
Rule:
"Never commit secrets."
is useful.
But:
Hook:
"BLOCK the operation when a secret is detected."
is stronger.
The ideal architecture is:
AI Agent
│
▼
Tool execution
│
▼
┌───────────┐
│ Hook │
└─────┬─────┘
│
┌──────┴──────┐
│ │
PASS BLOCK
│ │
▼ ▼
Execute tool Stop action
16. Example: Secret Detection Hook
Create:
hooks/security/scan-secrets.sh
Example:
#!/usr/bin/env bash
set -euo pipefail
if command -v gitleaks >/dev/null 2>&1; then
gitleaks detect \
--source . \
--no-banner \
--exit-code 1
else
echo "WARNING: gitleaks is not installed"
fi
Then integrate it into your agent's lifecycle according to the tool's hook configuration.
The exact hook configuration differs between Claude Code and Cursor, so keep the scanner script shared and the hook configuration tool-specific.
17. Claude Code Hooks
Claude Code has a comprehensive hook system with lifecycle events around tool execution and other agent operations. (Claude)
A practical Claude setup might enforce:
Before shell execution
↓
Validate command
↓
Allow / Block
After file modification
↓
Run formatting / validation
Before sensitive operation
↓
Security checks
This is especially useful for:
rm -rf
git reset
git push --force
production deployment
database migrations
secret exposure
18. Cursor Hooks
Cursor also provides lifecycle hooks through its current customization architecture. Cursor describes hooks as scripts that observe, control or extend the agent loop. (Cursor)
For example, conceptually:
beforeShellExecution
↓
validate-command.sh
and:
afterFileEdit
↓
format.sh
and:
beforeMCPExecution
↓
security validation
This lets you build a similar enforcement model in Cursor.
19. MCP: Give the AI Real Tools
MCP stands for Model Context Protocol.
Instead of the AI only seeing your source code, MCP can expose external systems.
For example:
AI Agent
│
┌──────────────┼───────────────┐
▼ ▼ ▼
GitHub Jira DB
│ │ │
▼ ▼ ▼
PRs Tickets Schema
Claude Code and Cursor both support MCP integrations. (Claude)
Useful MCP integrations include:
GitHub
Jira
Slack
PostgreSQL
Sentry
Linear
AWS
Internal APIs
Documentation
But don't expose everything.
Follow least privilege.
For example:
GitHub:
✓ Read repository
✓ Read issues
✓ Create PR
✗ Delete repository
✗ Modify organization settings
20. Practical MCP Example
Suppose your team uses Jira.
Without MCP:
Developer:
"Implement JIRA-123."
AI:
"I need the ticket details."
You manually copy them.
With MCP:
Developer:
"Implement JIRA-123."
AI
↓
Jira MCP
↓
Retrieve ticket
↓
Understand acceptance criteria
↓
Inspect code
↓
Implement
↓
Run tests
↓
Create PR
That is where AI starts becoming an actual development agent rather than a chatbot.
21. Create Reusable Commands
For repetitive workflows, create commands.
Examples:
/review
/security-audit
/fix-issue
/test
/refactor
/deploy
A /review workflow could be:
# Code Review
1. Inspect git diff.
2. Identify modified files.
3. Read relevant architecture rules.
4. Check correctness.
5. Check security.
6. Check performance.
7. Check tests.
8. Run tests.
9. Report findings by severity.
Cursor currently supports commands as reusable prompts, while its newer Skills system can also turn workflows into invocable /skill-name workflows. (Cursor)
22. A Better Modern Approach: Commands vs Skills
Don't blindly create both.
Use:
Skill
When the AI should be able to decide:
"This task requires security auditing."
Use:
security-audit/SKILL.md
Command
When the developer explicitly says:
/security-audit
Use an explicitly invoked workflow.
Subagent
When the task requires:
"Have a specialist independently analyze this."
Use:
security-auditor
Hook
When you need:
"This must be checked regardless of what the AI thinks."
Use a hook.
This distinction makes the system much cleaner.
23. Recommended AI Workflow for a Feature
Suppose you ask:
"Add a password reset API."
A well-configured AI environment should behave approximately like this:
USER REQUEST
│
▼
Understand requirements
│
▼
Read AGENTS.md / CLAUDE.md
│
▼
Load backend/API rules
│
▼
Inspect authentication architecture
│
▼
Create implementation plan
│
▼
Implement
│
├── Controller
├── Service
├── Repository
├── DTO
└── Tests
│
▼
Security Skill
│
├── Token security
├── Rate limiting
├── Enumeration risk
├── Input validation
└── Sensitive logging
│
▼
Run tests
│
▼
Typecheck
│
▼
Lint
│
▼
Code Reviewer
│
▼
Final diff
This is significantly more reliable than simply:
"Claude, implement password reset."
24. Practical Debugging Workflow
Suppose production has:
POST /api/orders
500 Internal Server Error
You can structure debugging like this:
Developer
│
▼
/debug
│
▼
Debugger Agent
│
├── Read logs
├── Trace request
├── Inspect service
├── Inspect database
└── Reproduce issue
│
▼
Root Cause
│
▼
Minimal Fix
│
▼
Regression Test
│
▼
Code Review
The critical part is:
Don't allow the AI to stop at "I found the likely cause."
Require:
Root cause
+
Fix
+
Regression test
+
Validation
25. Practical Database Migration Workflow
Database changes deserve their own rules.
Create:
database.mdc
Example:
---
description: Database migration rules
globs:
- "**/migrations/**"
- "**/*.sql"
---
# Database Rules
Never modify an already-applied migration.
For schema changes:
1. Create a new migration.
2. Make migrations backward compatible where possible.
3. Consider existing production data.
4. Consider indexes and query performance.
5. Test rollback strategy where supported.
6. Verify generated SQL.
7. Never drop production data without explicit approval.
Then create a migration skill:
database-migration/
└── SKILL.md
Now the AI has:
General instructions
+
Database-specific rules
+
Database migration workflow
without loading database-specific material into every task.
26. Context Management Matters
One of the biggest mistakes in AI coding projects is creating a gigantic:
CLAUDE.md
or:
AGENTS.md
containing 1,500 lines.
That is counterproductive.
Claude Code recommends keeping CLAUDE.md concise and moving multi-step or specialized procedures into skills or path-scoped rules. (Claude)
Cursor similarly recommends focused rules rather than one giant rule file. (Cursor)
A good architecture is:
AGENTS.md
│
├── Always relevant
│
└── ~100–200 lines
Rules
│
├── Backend
├── Frontend
├── Security
├── Testing
└── Database
Skills
│
├── Deployment
├── Security audit
├── Debugging
└── Migration
This gives the AI progressive context instead of dumping the entire engineering handbook into every request.
27. Use Path-Specific Rules
Suppose you have:
apps/api/
apps/web/
Don't tell the AI about React conventions while it is editing NestJS code.
Instead:
apps/api/**/*.ts
gets:
backend rules
while:
apps/web/**/*.tsx
gets:
frontend rules
Claude Code supports paths for conditional rules, while Cursor supports file-pattern-based rules through its .mdc configuration. (Claude)
This improves both relevance and context efficiency.
28. The Security Architecture I Recommend
For production development, I would implement this:
Developer
│
▼
AI Agent
│
┌────────┴────────┐
│ │
▼ ▼
Rules Skills
│ │
└────────┬────────┘
▼
Implementation
│
▼
┌──────────────┐
│ Hooks │
└──────┬───────┘
│
┌──────────────┼──────────────┐
▼ ▼ ▼
Gitleaks Secretlint ESLint
│ │ │
└──────────────┼──────────────┘
▼
Tests
│
▼
Security Agent
│
▼
Code Reviewer
│
▼
Git Diff
│
▼
PR
The AI is therefore inside the engineering controls, not above them.
29. Recommended Final Directory Structure
For a production Node.js/NestJS/React project, I would use:
my-project/
│
├── AGENTS.md
├── CLAUDE.md
│
├── apps/
│ ├── api/
│ └── web/
│
├── packages/
│ ├── shared/
│ └── config/
│
├── docs/
│ ├── architecture/
│ ├── api/
│ ├── decisions/
│ └── development/
│
├── tests/
│
├── .claude/
│ │
│ ├── rules/
│ │ ├── architecture.md
│ │ ├── backend.md
│ │ ├── frontend.md
│ │ ├── security.md
│ │ ├── testing.md
│ │ └── database.md
│ │
│ ├── skills/
│ │ ├── security-audit/
│ │ │ ├── SKILL.md
│ │ │ ├── scripts/
│ │ │ └── references/
│ │ │
│ │ ├── code-review/
│ │ │ └── SKILL.md
│ │ │
│ │ ├── debugging/
│ │ │ └── SKILL.md
│ │ │
│ │ ├── testing/
│ │ │ └── SKILL.md
│ │ │
│ │ └── deployment/
│ │ └── SKILL.md
│ │
│ ├── agents/
│ │ ├── security-auditor.md
│ │ ├── code-reviewer.md
│ │ ├── debugger.md
│ │ └── architecture-reviewer.md
│ │
│ └── settings.json
│
├── .cursor/
│ │
│ ├── rules/
│ │ ├── project.mdc
│ │ ├── architecture.mdc
│ │ ├── backend.mdc
│ │ ├── frontend.mdc
│ │ ├── security.mdc
│ │ ├── testing.mdc
│ │ └── database.mdc
│ │
│ ├── skills/
│ │ ├── security-audit/
│ │ │ └── SKILL.md
│ │ ├── code-review/
│ │ │ └── SKILL.md
│ │ ├── debugging/
│ │ │ └── SKILL.md
│ │ └── deployment/
│ │ └── SKILL.md
│ │
│ ├── agents/
│ │ ├── security-auditor.md
│ │ ├── code-reviewer.md
│ │ ├── debugger.md
│ │ └── architecture-reviewer.md
│ │
│ ├── hooks.json
│ └── mcp.json
│
├── hooks/
│ ├── security/
│ │ ├── gitleaks.sh
│ │ ├── secretlint.sh
│ │ └── validate-command.sh
│ │
│ ├── validation/
│ │ ├── lint.sh
│ │ ├── format.sh
│ │ └── typecheck.sh
│ │
│ └── audit/
│ └── agent-audit.sh
│
├── .gitignore
├── package.json
└── README.md
30. What Should Actually Be Shared Between Claude and Cursor?
This is the part I would optimize carefully.
You don't want:
Claude implementation
+
Cursor implementation
+
duplicated rules
+
duplicated skills
Instead:
Shared
│
┌───────┴────────┐
│ │
AGENTS.md Skills
│ │
┌──────┴──────┐ │
▼ ▼ ▼
Claude Code Cursor Shared
│ │ workflows
│ │
.claude/ .cursor/
Cursor's current Skills implementation explicitly supports compatibility with Claude skill directories, including .claude/skills/, which makes sharing skills considerably easier. (Cursor)
Claude Code also supports importing other coding-agent configurations, including AGENTS.md, Cursor rules, MCP servers, commands, subagents and skills in current versions. (Claude)
That means the ecosystem is moving toward portable AI development configuration, rather than completely isolated tool-specific configurations.
31. What I Would NOT Put in AI Instructions
Avoid putting these into CLAUDE.md or AGENTS.md:
Huge documentation
Full API documentation
Full database schema
Entire architecture document
Instead:
docs/
and tell the AI where to find it.
Temporary information
Don't put:
Currently fixing ticket #123
into permanent project instructions.
Secrets
Never:
API_KEY=xxxxx
DATABASE_PASSWORD=xxxxx
AI configuration should reference environment variables.
Extremely detailed procedures
Move them into:
skills/
Enforcement rules
Don't rely on:
"Never run dangerous commands."
alone.
Use hooks and permissions where available.
32. The Golden Rule
Think about your AI configuration as an engineering system:
KNOWLEDGE
│
AGENTS.md
│
▼
RULES
│
▼
SKILLS
│
▼
SUBAGENTS
│
▼
TOOLS
│
▼
HOOKS
│
▼
VALIDATION
Each layer solves a different problem.
AGENTS.md / CLAUDE.md
What should the AI know?
Rules
What standards must it follow?
Skills
How should it perform this type of task?
Subagents
Which specialist should handle this task?
MCP
Which external systems can it access?
Hooks
Which actions must be validated or blocked?
Tests
Did the implementation actually work?
33. My Recommended Starting Point
Don't build the entire structure on day one.
Start with this:
project/
│
├── AGENTS.md
├── CLAUDE.md
│
├── .claude/
│ ├── rules/
│ │ ├── security.md
│ │ ├── backend.md
│ │ └── testing.md
│ │
│ ├── skills/
│ │ ├── security-audit/
│ │ │ └── SKILL.md
│ │ └── code-review/
│ │ └── SKILL.md
│ │
│ └── agents/
│ ├── security-auditor.md
│ └── code-reviewer.md
│
└── .cursor/
├── rules/
├── skills/
├── agents/
├── hooks.json
└── mcp.json
Then evolve it based on actual failures.
If the AI repeatedly makes a mistake:
mistake #1 → fix manually
mistake #2 → add a rule
mistake #3 → automate it
That is the right way to grow the scaffolding.
34. Final Architecture
The end state should look less like:
Claude/Cursor
↓
Generate code
and more like:
┌───────────────────┐
│ Developer │
└─────────┬─────────┘
│
▼
┌───────────────────┐
│ Claude / Cursor │
│ Agent │
└─────────┬─────────┘
│
┌───────────┴───────────┐
│ │
▼ ▼
Project Rules Skills
│ │
└───────────┬───────────┘
│
▼
Subagents
│
┌─────────────┼─────────────┐
▼ ▼ ▼
Developer Security Reviewer
Agent Agent Agent
│ │ │
└─────────────┼─────────────┘
▼
MCP / Tools
│
▼
Code Changes
│
▼
Hooks
│
┌───────────┼───────────┐
▼ ▼ ▼
Secrets Lint Tests
│ │ │
└───────────┼───────────┘
▼
Final Review
│
▼
PR
That is the fundamental shift from AI-assisted coding to an AI-native software engineering workflow.
The current Claude Code and Cursor feature sets make this architecture practical: Claude Code provides persistent instructions, path-scoped rules, skills, subagents, hooks, MCP and auto memory; Cursor provides project rules/AGENTS.md, Agent Skills, subagents, hooks, MCP and a unified Customize/Plugin system. (Claude)
The most important design principle is to keep the AI configuration modular and the enforcement deterministic. Let the model reason about code, but let tests, scanners, permissions and hooks enforce the things that cannot safely depend on model compliance.