# Project Conventions

> >

- **Type:** Skill
- **Install:** `agentstack add skill-nasrulhazim-agent-skills-project-conventions`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [nasrulhazim](https://agentstack.voostack.com/s/nasrulhazim)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [nasrulhazim](https://github.com/nasrulhazim)
- **Source:** https://github.com/nasrulhazim/agent-skills/tree/main/skills/project-conventions

## Install

```sh
agentstack add skill-nasrulhazim-agent-skills-project-conventions
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Self-Update Practice

`CLAUDE.md` is a **living document**. Claude must update it immediately whenever something
worth remembering is discovered — corrections, preferences, patterns, or gotchas.

The rule: **A slightly redundant note is better than repeating a mistake.**

---

## When to Update CLAUDE.md

Update immediately when any of these occur:

| Trigger | Example |
|---|---|
| User corrects a mistake | "jangan guna MySQL, kita pakai PostgreSQL" |
| User expresses a preference | "aku tak suka pattern ni, guna cara lain" |
| Better pattern discovered during implementation | Realising a cleaner approach mid-task |
| Gotcha or edge case found | A library behaves unexpectedly, an assumption was wrong |
| Architectural decision made | "kita guna UUIDs, bukan auto-increment" |
| Naming or style preference | "method names in camelCase, not snake_case" |
| Tool or stack choice confirmed | "pakai Pest, bukan PHPUnit" |
| Testing preference confirmed | "pakai Pest describe blocks", "PHPStan level 8" |
| Deployment preference confirmed | "deploy via GitHub Actions", "Docker for staging" |

Do **not** wait until the end of the session. Update `CLAUDE.md` **as soon as** the
correction or preference is identified — then continue with the task.

---

## Update Procedure

When a trigger is detected:

1. **Apply the fix** to the current task first
2. **Read the current `CLAUDE.md`** to find the right section
3. **Insert the update** in the appropriate section:
   - Preference / style → `## Preferences` or relevant stack section
   - DO/DON'T → `## DO / DON'T`
   - Architectural → update the relevant architecture section
   - Gotcha / edge case → add under the relevant section with `> **Gotcha:**` callout
4. **Do not announce every update** unless the user asks — just do it silently and continue

---

## Format Rules

### Gotcha Format

```markdown
> **Gotcha:** PostgreSQL `uuid-ossp` extension must be enabled before using
> `DB::raw('uuid_generate_v4()')`. Prefer letting Laravel handle UUID generation
> from PHP side via `InteractsWithUuid` trait instead.
```

Use `> **Gotcha:**` for any surprise, trap, or non-obvious behaviour that could cause
a future mistake if forgotten.

### DO / DON'T Format

```markdown
## DO / DON'T

- ✅ DO use `InteractsWithUuid` trait for UUID generation
- ❌ DON'T use `DB::raw('uuid_generate_v4()')` directly
- ✅ DO write tests with Pest
- ❌ DON'T use PHPUnit syntax in this project
```

### Preference Format

State preferences as facts, not opinions:

```markdown
## Preferences

- Database: PostgreSQL (not MySQL)
- ORM: Eloquent — no raw query builders unless necessary
- Tests: Pest — BDD-style `it()` and `describe()` blocks
- Migrations: always reversible — implement `down()` properly
```

---

## Testing Preferences to Track

When the user confirms testing preferences, record under `## Testing` in CLAUDE.md:

```markdown
## Testing

- Framework: Pest (BDD-style `it()` and `describe()` blocks)
- PHPStan Level: 8 (with Larastan)
- Pint Preset: laravel
- Rector: PHP 8.2 set enabled
- Coverage: minimum 80% on critical paths
- Arch Tests: strict types enforced, no `dd()` in src/
```

Common triggers:
- User sets PHPStan level → record level and any baseline file
- User chooses Pest patterns → record `describe/it` vs flat `test()` preference
- User configures Pint → record preset choice and any custom rules
- User sets up Rector → record which rule sets are active

---

## Deployment Preferences to Track

When deployment patterns are confirmed, record under `## Deployment` in CLAUDE.md:

```markdown
## Deployment

- CI: GitHub Actions (Pint → PHPStan → Rector → Pest)
- CD: SSH deploy to VPS via `/bin/deploy.sh`
- Docker: Laravel Sail for dev, custom Dockerfile for prod
- Staging: auto-deploy on push to `staging` branch
- Production: manual trigger after staging verification
- Backup: daily via `/bin/backup.sh`
```

Common triggers:
- User configures CI/CD pipeline → record workflow structure
- User sets up Docker → record dev vs prod distinction
- User confirms deployment target → record server/platform details
- User establishes branching strategy → record branch → environment mapping

---

## What NOT to Record

| Skip | Reason |
|---|---|
| One-off task decisions | Don't affect future work |
| Things in Laravel / package docs | Already discoverable |
| Obvious conventions | Noise without value |
| Temporary workarounds | Mark clearly as temporary if recorded |

---

## CLAUDE.md Structure

If no `CLAUDE.md` exists in the project, create one using this structure.
Read `references/claude-md-template.md` for the full starter template.

Minimum sections for any project:

```markdown
# CLAUDE.md — [Project Name]

## Project Overview
## Stack
## Architecture
## DO / DON'T
## Preferences
## Gotchas
## Changelog (of this file)
```

---

## Initialising CLAUDE.md for a New Project

When the user says "buat CLAUDE.md" or starts a new project without one:

1. Ask 3 questions max — don't over-interview:
   - What is this project? (name + one sentence)
   - Stack? (language, framework, DB, key packages)
   - Any immediate preferences or constraints to record?

2. Generate the file using `references/claude-md-template.md`

3. Tell the user: "CLAUDE.md dah buat. Aku akan update automatically bila ada
   corrections, preferences, atau gotchas sepanjang kita kerja."

---

## Reference Files

| File | Read When |
|---|---|
| `references/claude-md-template.md` | Creating a new CLAUDE.md from scratch |

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [nasrulhazim](https://github.com/nasrulhazim)
- **Source:** [nasrulhazim/agent-skills](https://github.com/nasrulhazim/agent-skills)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-nasrulhazim-agent-skills-project-conventions
- Seller: https://agentstack.voostack.com/s/nasrulhazim
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.