diff --git a/src/Capabilities/Deprecated.php b/src/Capabilities/Deprecated.php
new file mode 100644
index 0000000000000000000000000000000000000000..2688869dde198d2d1947bfc159a7518ce40fd60c
--- /dev/null
+++ b/src/Capabilities/Deprecated.php
@@ -0,0 +1,41 @@
+<?php declare(strict_types = 1);
+
+namespace Grifart\ClassScaffolder\Capabilities;
+
+use Grifart\ClassScaffolder\ClassInNamespace;
+use Grifart\ClassScaffolder\Definition\ClassDefinition;
+use function sprintf;
+
+
+final class Deprecated implements Capability
+{
+
+	/**
+	 * @param class-string $replacement
+	 */
+	public function __construct(
+		private ?string $description = null,
+		private ?string $replacement = null,
+	) {}
+
+
+	public function applyTo(
+		ClassDefinition $definition,
+		ClassInNamespace $draft,
+		?ClassInNamespace $current,
+	): void
+	{
+		$annotation = '@deprecated';
+		if ($this->description !== null) {
+			$annotation .= ' ' . $this->description;
+		}
+
+		if ($this->replacement !== null) {
+			$annotation .= $this->description !== null ? ', ' : ' ';
+			$annotation .= sprintf('use {@see %s} instead', $this->replacement);
+		}
+
+		$draft->getClassType()->addComment($annotation);
+	}
+
+}
diff --git a/src/Capabilities/functions.php b/src/Capabilities/functions.php
index 628824e9a2689b498366eea6f5d3efa7b31decdb..e46e37ab6bf0406f652a7b017484b5c33b9574ba 100644
--- a/src/Capabilities/functions.php
+++ b/src/Capabilities/functions.php
@@ -8,6 +8,16 @@ function constructorWithPromotedProperties(): ConstructorWithPromotedProperties
 	return new ConstructorWithPromotedProperties();
 }
 
+/**
+ * @param class-string $replacement
+ */
+function deprecated(
+	?string $description = null,
+	?string $replacement = null,
+): Deprecated {
+	return new Deprecated($description, $replacement);
+}
+
 function getters(): Getters {
 	return new Getters();
 }
diff --git a/tests/Capabilities/Deprecated/DeprecatedTest.expected.onlyAnnotation.phps b/tests/Capabilities/Deprecated/DeprecatedTest.expected.onlyAnnotation.phps
new file mode 100644
index 0000000000000000000000000000000000000000..dab05666728caae98fd6d3d1987bcfd2aad60d33
--- /dev/null
+++ b/tests/Capabilities/Deprecated/DeprecatedTest.expected.onlyAnnotation.phps
@@ -0,0 +1,14 @@
+<?php
+
+/**
+ * Do not edit. This is generated file. Modify definition file instead.
+ */
+
+declare(strict_types=1);
+
+/**
+ * @deprecated
+ */
+final class ClassName
+{
+}
diff --git a/tests/Capabilities/Deprecated/DeprecatedTest.expected.withAll.phps b/tests/Capabilities/Deprecated/DeprecatedTest.expected.withAll.phps
new file mode 100644
index 0000000000000000000000000000000000000000..3a5ac7dad05a30b5c5bc42c878a1d8914063a22f
--- /dev/null
+++ b/tests/Capabilities/Deprecated/DeprecatedTest.expected.withAll.phps
@@ -0,0 +1,14 @@
+<?php
+
+/**
+ * Do not edit. This is generated file. Modify definition file instead.
+ */
+
+declare(strict_types=1);
+
+/**
+ * @deprecated will be removed in v4.0.0, use {@see Grifart\ClassScaffolder\Test\Capabilities\Deprecated\Replacement} instead
+ */
+final class ClassName
+{
+}
diff --git a/tests/Capabilities/Deprecated/DeprecatedTest.expected.withDescription.phps b/tests/Capabilities/Deprecated/DeprecatedTest.expected.withDescription.phps
new file mode 100644
index 0000000000000000000000000000000000000000..0adb6be8525ac715aec839c23577fea793816a44
--- /dev/null
+++ b/tests/Capabilities/Deprecated/DeprecatedTest.expected.withDescription.phps
@@ -0,0 +1,14 @@
+<?php
+
+/**
+ * Do not edit. This is generated file. Modify definition file instead.
+ */
+
+declare(strict_types=1);
+
+/**
+ * @deprecated will be removed in v4.0.0
+ */
+final class ClassName
+{
+}
diff --git a/tests/Capabilities/Deprecated/DeprecatedTest.expected.withReplacement.phps b/tests/Capabilities/Deprecated/DeprecatedTest.expected.withReplacement.phps
new file mode 100644
index 0000000000000000000000000000000000000000..863e538e0e599a261302cbfb4d7b77ef25a91802
--- /dev/null
+++ b/tests/Capabilities/Deprecated/DeprecatedTest.expected.withReplacement.phps
@@ -0,0 +1,14 @@
+<?php
+
+/**
+ * Do not edit. This is generated file. Modify definition file instead.
+ */
+
+declare(strict_types=1);
+
+/**
+ * @deprecated use {@see Grifart\ClassScaffolder\Test\Capabilities\Deprecated\Replacement} instead
+ */
+final class ClassName
+{
+}
diff --git a/tests/Capabilities/Deprecated/DeprecatedTest.phpt b/tests/Capabilities/Deprecated/DeprecatedTest.phpt
new file mode 100644
index 0000000000000000000000000000000000000000..1962e7c1aa673df5ad9a6db2e7b124161b583d88
--- /dev/null
+++ b/tests/Capabilities/Deprecated/DeprecatedTest.phpt
@@ -0,0 +1,69 @@
+<?php declare(strict_types = 1);
+
+namespace Grifart\ClassScaffolder\Test\Capabilities\Deprecated;
+
+use Grifart\ClassScaffolder\ClassGenerator;
+use Grifart\ClassScaffolder\Definition\ClassDefinition;
+use Tester\Assert;
+use Tester\TestCase;
+use function Grifart\ClassScaffolder\Capabilities\deprecated;
+use function Grifart\ClassScaffolder\Definition\definitionOf;
+
+
+require __DIR__ . '/../../bootstrap.php';
+
+final class DeprecatedTest extends TestCase
+{
+	private function doAssert(
+		ClassDefinition $definition,
+		string $expectedFilePath,
+	): void
+	{
+		$generator = new ClassGenerator();
+		$phpFile = $generator->generateClass($definition);
+		$code = (string) $phpFile;
+
+		Assert::matchFile($expectedFilePath, $code);
+	}
+
+	public function testWithoutParams(): void
+	{
+		$this->doAssert(
+			definition: definitionOf('ClassName')
+				->with(deprecated()),
+			expectedFilePath: __DIR__ . '/DeprecatedTest.expected.onlyAnnotation.phps',
+		);
+	}
+
+	public function testWithDescription(): void
+	{
+		$this->doAssert(
+			definition: definitionOf('ClassName')
+				->with(deprecated(description: 'will be removed in v4.0.0')),
+			expectedFilePath: __DIR__ . '/DeprecatedTest.expected.withDescription.phps',
+		);
+	}
+
+	public function testWithReplacement(): void
+	{
+		$this->doAssert(
+			definition: definitionOf('ClassName')
+				->with(deprecated(replacement: Replacement::class)),
+			expectedFilePath: __DIR__ . '/DeprecatedTest.expected.withReplacement.phps',
+		);
+	}
+
+	public function testWithAll(): void
+	{
+		$this->doAssert(
+			definition: definitionOf('ClassName')
+				->with(deprecated(
+					description: 'will be removed in v4.0.0',
+					replacement: Replacement::class,
+				)),
+			expectedFilePath: __DIR__ . '/DeprecatedTest.expected.withAll.phps',
+		);
+	}
+}
+
+(new DeprecatedTest())->run();
diff --git a/tests/Capabilities/Deprecated/Replacement.php b/tests/Capabilities/Deprecated/Replacement.php
new file mode 100644
index 0000000000000000000000000000000000000000..af323fc2767c2f2d0162d0926639d00980f3f8d8
--- /dev/null
+++ b/tests/Capabilities/Deprecated/Replacement.php
@@ -0,0 +1,7 @@
+<?php declare(strict_types = 1);
+
+namespace Grifart\ClassScaffolder\Test\Capabilities\Deprecated;
+
+
+final class Replacement
+{}